CLI Reference

Table of Contents

• attach
• build
• build-history
• cat
• dashboard
• edit
• exec
• export
• image
• info
• inspect
• install
• kill
• logs
• promote
• ps
• router
• run
• rm
• scale
• stage
• system-logs
• system-features
• uninstall
• up
• weight

attach

Attach to a process running in a container

Usage

rio attach [OPTIONS] CONTAINER

Options

flag	aliases	description	default
--timeout value		Timeout waiting for the container to be created to attach to	1m
--pod value		Specify pod, default is first pod found

Examples

rio attach demo

rio attach --timeout 30s --pod mydemopod demo

---

build

Build a docker image using buildkitd

Usage

rio build command [command options] [arguments...]

Options

flag	aliases	description	default
--file value	-f	Name of the file to look for build, support both Riofile and Dockerfile
--tag value	-t	Name and optionally a tag in the 'name:tag' format
--build-arg		Set build-time variables
--no-cache		Do not use cache when building the image
--help	-h	show help

Examples

# Navigate to directory with Dockerfile and build it into local registry
rio build -t test:v1

# See image that was build
rio image

# Build from riofile insted
rio build -t test:v1 --no-cache -f Riofile.yaml

# Now run the image
rio run -n test -p 8080 localhost:5442/default/test:v1

# Build the image again with new tag
rio build -t test:v2

# Now stage the 2nd image
rio stage --image localhost:5442/default/test:v2 test v2

---

build-history

Show previous builds

Usage

rio build-history [command options] [arguments...]

Options

flag	aliases	description	default
--quiet	-q	Only display Names
--format value		'json' or 'yaml' or Custom format: {{ "'{{.Obj.Name}}'" }} [$FORMAT]

Examples

# see previous builds from stacks or workloads
rio build-history

# custom output format
rio build-history --format {{ "{{.Obj.Name}}" }}

---

cat

Print the contents of a config

Usage

rio cat [OPTIONS] [NAME...]

Options

flag	aliases	description	default
--key	-k	The values which to cat

Examples

# cat a configmap
rio cat configmap/config-foo

# cat a key from a configmap
rio cat --key=a configmap/config-foo

---

dashboard

Open the dashboard in a browser

Usage

rio dashboard [OPTIONS]

Options

flag	aliases	description	default
--reset-admin		Reset admin password

Examples

# reset admin pw
rio dashboard --reset-admin 

---

edit

Edit resources

Usage

rio edit [TYPE/]RESOURCE_NAME

Options

flag	aliases	description	default
--raw		Edit the raw API object, not the pretty formatted one

Examples

rio edit demo@v4

rio edit router/myrouter

---

exec

Run a command in a running container

Usage

rio exec [OPTIONS] CONTAINER COMMAND [ARG...]

Options

flag	aliases	description	default
--stdin	-i	Pass stdin to the container
--tty	-t	Stdin is a TTY
--container value	-c value	Specify container in pod, default is first container
--pod value		Specify pod, default is first pod found

Examples

# ssh into running container
rio exec -it demo sh

# this is equivalent of doing
rio exec --tty --stdin demo sh

# choose pod and container
rio exec -it --pod mypod --container server demo sh

---

export

Export a namespace or service

Usage

rio export [TYPE/]NAMESPACE_OR_SERVICE

Options

flag	aliases	description	default
--format value		Specify output format, yaml/json. Defaults to yaml	yaml
--riofile		Export riofile format

Examples

# export a service
rio export demo

# export a namespace in riofile format
rio export --riofile namespace/default

---

image

List images built from the local registry

Usage

rio image

---

info

Show system info

Usage

rio info

---

inspect

Inspect resources

Usage

rio inspect [TYPE/][NAMESPACE/]SERVICE_NAME

Options

flag	aliases	description	default
--format		Edit the raw API object, not the pretty formatted one

Examples

rio inspect svc@v2

# inspect a build
rio inspect taskrun/affectionate-mirzakhani-mfp5q-ee709-4e40c

---

install

Install the Rio management plane

See the install docs for more info.

Usage

rio install [OPTIONS]

Options

flag	aliases	description	default
--check		Only check status, don't deploy controller
--disable-features value		Manually specify features to disable, supports comma separated values
--enable-debug		Enable debug logging in controller
--ip-address value		Manually specify IP addresses to generate rdns domain, supports comma separated values
--yaml		Only print out k8s yaml manifest
--rdns-url		Specify Rdns server url to use	https://api.on-rio.io/v1

--check

Check if Rio is installed in the current cluster without deploying the Rio controller. If Rio has not been installed, this command might hang on Waiting for rio controller to initialize.

--disable-features

Choose features to be disabled when starting the Rio control plane. Below are a list of available features

Feature	Description
autoscaling	Auto-scaling services based on in-flight requests
build	Rio Build, from source code to deployment
gloo	API gateway backed by gloo
linkerd	Linkerd service mesh
letsencrypt	Let's Encrypt
rdns	Acquire DNS from public Rancher DNS service
dashboard	Rio UI

--ip-address

Manually specify IPAddress for API gateway services. The IP will be used to generate a record for the cluster domain. By default, if this flag is not specified, Rio will use the IP of Service Loadbalancer that points to API gateway.

Note: If service loadbalancer cannot be provisioned, Nodeport is used to expose API gateway.

Examples

# basic install
rio install

# install with debug and disable some features
rio install --enable-debug --disable-features linkerd,gloo

# print yaml to run manually, with custom ip-address
rio install --yaml --ip-address 127.0.0.1

---

kill

Kill pods individually or all pods belonging to a service

Usage

rio kill [SERVICE_NAME/POD_NAME]

Examples

# kill a service
rio kill demo

# kill individual pods
rio pods # first get pod name
rio kill pod/demo-v042dxp-5fb7d8f677-f9xgn

---

logs

Print logs from services or containers

Usage

rio logs [OPTIONS] SERVICE/BUILD

Options

flag	aliases	description	default
--since value	-s value	Logs since a certain time, either duration (5s, 2m, 3h) or RFC3339	"24h"
--timestamps	-t	Print the logs with timestamp
--tail value	-n value	Number of recent lines to print, -1 for all	200
--container value	-c value	Print the logs of a specific container, use -a for system containers
--previous	-p	Print the logs for the previous instance of the container in a pod if it exists, excludes running
--init-containers		Include or exclude init containers
--all	-a	Include hidden or systems logs when logging
--no-color	--nc	Dont show color when logging
--output value	-o value	Output format: [default, raw, json]	default

Examples

# get logs from a service
rio logs demo

# Get logs from a build
rio build-history
rio logs taskrun/affectionate-mirzakhani-mfp5q-ee709-4e40c

# get 1 previous log line for the linkerd-proxy in demo service
rio logs --tail 1 --container linkerd-proxy -a demo

# ignore init-containers and filter to waiting or terminated pods, include timestamps
rio logs --container-state "terminated,waiting" --init-containers=false --timestamps demo

# target terminated pods of all kinds, format as json
rio logs -p -a  --output json demo

---

Promote

Send 100% of traffic to an app version and scale down other versions. See also weight.

Usage

rio promote [OPTIONS] SERVICE_NAME

Options

flag	aliases	description	default
--duration	none	How long the rollout should take. An approximation, actual time may fluctuate	0s
--pause	none	Whether to pause all rollouts on current app	false

Examples

# promote n@v2 
rio promote n@v2

# promote n@v2 over 1 hour 
rio promote --duration=1h n@v2

# pause last command
rio promote --pause=true n@v2

---

ps

List services

Usage

rio ps [OPTIONS]

Options

flag	aliases	description	default
--quiet	-q	Only display Names
--format		'json' or 'yaml' or Custom format: {{ "'{{.Name}} {{.Obj.Name}}'" }} [$FORMAT]
--all	-a	print all resources, including router and externalservice
--workloads	-w	include apps/v1 Deployments and DaemonSets in output

Examples

# show services and workloads
rio ps -w

# output json
rio ps --format json

# display name and weight in custom format
rio ps --format {{ "{{.Obj.Name}} -> {{.Data.Weight}}" }}

---

router

Route traffic across the mesh

Usage

rio routers command [command options] [arguments...]

Options

flag	aliases	description	default
--quiet	-q	Only display Names
--format		'json' or 'yaml' or Custom format: {{ "'{{.Name}} {{.Obj.Name}}'" }} [$FORMAT]

Examples

# show existing routers
rio route

add/create

Create a router. By default appends at the end.

Services specified without a version are assumed to be apps. For example rio route add x to svc would target the svc app endpoint, not the svc@v0 version.

Usage

rio router create/add MATCH ACTION [TARGET...]

Options

flag	aliases	description	default
--insert		Insert the rule at the beginning instead of the end
--header value		Match HTTP header (format key=value, value optional)
--fault-percentage value		Percentage of matching requests to fault	0
--fault-delay-milli-seconds value		Inject a delay for fault in milliseconds	0
--fault-httpcode value		HTTP code to send for fault injection	0
--add-header value		Add HTTP header to request (format key=value)
--set-header value		Override HTTP header to request (format key=value)
--remove-header value		Remove HTTP header to request (format key=value)
--retry-attempts value		How many times to retry	0
--retry-timeout-seconds value		Timeout per retry in seconds	0
--timeout-seconds value		Timeout in seconds for all requests	0
--method value		Match HTTP method, support comma-separated values

Examples

# route to the demo app endpoint
rio route add myroute to demo

# route a specific path to the demo app's version 0, and insert into first slot
rio route add --insert myroute/name.html to demo@v0

See the routers readme for advanced example usage.

---

run

Create and run a new service

Usage

rio run [OPTIONS] IMAGE [COMMAND] [ARG...]

Options

flag	aliases	description	default
--add-host value		Add a custom host-to-IP mapping (host=ip)
--annotations value		Annotations to attach to this service
--build-branch value		Build repository branch	master
--build-dockerfile value		Set Dockerfile name	defaults to Dockerfile
--build-context value		Set build context	.
--build-webhook-secret value		Set GitHub webhook secret name
--build-docker-push-secret value		Set docker push secret name
--build-clone-secret value		Set git clone secret name
--build-image-name value		Specify custom image name to push
--build-registry value		Specify to push image to
--build-revision value		Build git commit or tag
--build-pr		Enable builds on new pull requests
--build-tag		Enable builds on any new tags instead of new commits on a branch, requires webhook, does not support polling
--build-tag-include		Pattern that tags must match
--build-tag-exclude		Pattern that excludes tags
--build-timeout value		Timeout for build, ( (ms/s/m/h))	10m
--command value		Overwrite the default ENTRYPOINT of the image
--config value		Configs to expose to the service (format: name[/key]:target)
--concurrency value		The maximum concurrent request a container can handle (autoscaling)	10
--cpus value		Number of CPUs
--dns value		Set custom DNS servers
--dnsoption value		Set DNS options (format: key:value or key)
--dnssearch value		Set custom DNS search domains
--env value	-e value	Set environment variables
--env-file value		Read in a file of environment variables
--global-permission value		Permissions to grant to container's service account for all namespaces
--group value		The GID to run the entrypoint of the container process
--health-cmd value		Command to run to check health
--health-failure-threshold value		Consecutive failures needed to report unhealthy	0
--health-header value		HTTP Headers to send in GET request for healthcheck
--health-initial-delay value		Start period for the container to initialize before starting healthchecks ( (ms/s/m/h))	"0s"
--health-interval value		Time between running the check ( (ms/s/m/h))	"0s"
--health-success-threshold value		Consecutive successes needed to report healthy	0
--health-timeout value		Maximum time to allow one check to run ( (ms/s/m/h))	"0s"
--health-url value		URL to hit to check health (example: http://:8080/ping)
--host-dns		Use the host level DNS and not the cluster level DNS
--hostname value		Container host name
--image-pull-policy value		Behavior determining when to pull the image (never/always/not-present)	"not-present"
--image-pull-secrets value		Specify image pull secrets
--interactive	-i	Keep STDIN open even if not attached
--label-file value		Read in a line delimited file of labels
--label value	-l value	Set meta data on a container
--memory value	-m value	Memory reservation (format: [], where unit = b, k, m or g)
--name value	-n value	Assign a name to the container. Use format [namespace:]name[@version]
--net value		Set network mode (host)
--no-mesh		Disable service mesh
--permission value		Permissions to grant to container's service account in current namespace
--ports value	-p value	Publish a container's port(s) (format: svcport:containerport/protocol)
--privileged		Run container with privilege
--read-only		Mount the container's root filesystem as read only
--rollout-duration value		How long the rollout should take. An approximation, actual time may fluctuate. Affects template services, but not weight or promote commands.	"0s"
--request-timeout-seconds value		Set request timeout in seconds	0
--scale value		The number of replicas to run or a range for autoscaling (example 1-10)
--secret value		Secrets to inject to the service (format: name[/key]:target)
--stage-only		Only stage service when generating new services. Can only be used when template is true
--template		If true new version is created per git commit. If false update in-place
--tty	-t	Allocate a pseudo-TTY
--user value	-u value	UID[:GID] Sets the UID used and optionally GID for entrypoint process (format: [:])
--volume value	-v value	Specify volumes for for services
--weight value		Specify the weight for the services	0
--workdir value	-w value	Working directory inside the container

Examples

# basic run
rio run -p 80 nginx

# run a named service with set scale, concurrency and ports. Build an image from a github repo
rio run -n mysvc --scale 5-10 --concurrency 5 -p 80:8080/http https://github.com/rancher/rio-demo

# add a version to service
rio run --weight 50 -n mysvc@v2 -p 80 nginx

# set custom readiness probe
rio run --health-url http://:8080/status --health-initial-delay 10s --health-interval 5s --health-failure-threshold 5 --health-timeout 5s -p 8080 cbron/mybusybox:dev

# set permission for containers. By setting permissions, rio will assign a serviceaccount to the pod which will have the corresponding permissions. Global permission means permissions across all namespaces.
rio run --global-permission "create,update,delete services" --permission "* apps/deployments" nginx

# set host:ip entry in container
rio run --add-host db=1.2.3.4 nginx

# set build parameters
rio run --build-branch dev --build-dockerfile Dockerfile.production --build-context . --build-webhook-secret webhook https://github.com/example/exmaple 

# run a service that deploy on any new tag matching '^v' and not match 'alpha'
rio run -p 8080 -n tag-demo --build-webhook-secret=githubtoken --build-tag=true --build-tag-include="^v" --build-tag-exclude="alpha" https://github.com/rancher/rio-demo

---

rm

Delete resources

Usage

rio rm [TYPE/]RESOURCE_NAME

Examples

# delete service foo
rio rm foo

# delete multiple resources of different types
rio rm svc1 svc2 router/route1 externalservice/foo

---

scale

Scale a service to a desired number, or set autoscaling params

Usage

rio scale [SERVICE=NUMBER_OR_MIN-MAX...]

Examples

rio scale foo=5

# autoscaling
rio scale foo=1-5

---

stage

Stage a new revision of a service

Note that when using --edit certain values (like spec.weight) will be overwritten, and other flags (like --env) won't take effect.

Usage

rio stage [OPTIONS] SERVICE NEW_REVISION

Options

flag	aliases	description	default
--image value		Runtime image (Docker image/OCI image)
--edit		Edit the config to change the spec in new revision
--env value	-e value	Set environment variables
--env-file value		Read in a file of environment variables

Examples

# stage an image (tag v3) to the 2nd version of the demo service
rio stage --image ibuildthecloud/demo:v3 demo v2

# stage the same image with different env variables
rio stage -e abc=xyz demo v2

# stage but edit first
rio stage --edit demo v2

---

system logs

Print the logs from the Rio management plane

Usage

rio system logs

---

system feature

View/Edit system feature/configuration

Uasge

# view system feature
rio system feature

# edit system feature/configuration
rio system feature --edit

---

uninstall

Uninstall rio

Usage

rio uninstall [OPTIONS]

Options

flag	aliases	description	default
--namespace value		namespace to install system resources	"rio-system"

Examples

rio uninstall

rio uninstall --namespace alt-namespace

---

up

Apply a Riofile

Usage

rio up [OPTIONS]

Options

flag	aliases	description	default
--name value	-n	Set stack name, defaults to current directory name
--answers value		Set answer file
--file value	-f value	Set rio file
--parallel	-p	Run builds in parallel
--branch value		Set branch when pointing stack to git repo	master
--revision value		Use a specific commit hash
--build-webhook-secret value		Set GitHub webhook secret name
--build-tag		Enable builds on any new tags instead of new commits on a branch, requires webhook, does not support polling
--build-tag-include		Pattern that tags must match
--build-tag-exclude		Pattern that excludes tags
--build-clone-secret value		Set name of secret to use with git clone
--push-registry-secret value		Set secret for pushing to custom registry
--permission value		Permissions to grant to container's service account in current namespace

Examples

# apply a file named 'Riofile' in current directory
rio up

# apply stack.yaml as a stack named mystack as 2nd revision
rio up --name mystack -f stack.yaml -p

# apply a riofile from git repo, from a specific branch and commit, using a secret, and setup webhook.
rio up --branch branchname --build-webhook-secret=githubtoken --build-clone-secret=mysecret --revision {commit_sha}  https://github.com/exmaple/example

# Set custom permissions to give the stack, and supply answers to riofile questions
rio up  --permissions '* configmaps' --answers answerfile.yaml

---

weight

Set the percentage of traffic to allocate to a given service version. See also promote.

Defaults to an immediate rollout, set duration to perform a gradual rollout

Note that once a service version is set to 100% of weight, you must assign weight to other services in order to route traffic to them. For instance if you have svc-a and svc-b, and you set svc-a=100% and then svc-a=50%, svc-b will still have 0% weight and svc-a will still have 100%. You must set svc-b=50% to give it weight.

Usage

rio weight [OPTIONS] SERVICE_NAME=PERCENTAGE

Options

flag	aliases	description	default
--duration		How long the rollout should take. An approximation, actual time may fluctuate	0s
--pause		Whether to pause all rollouts on current app	false

Examples

# immediately shift 100% of traffic to app n@v0
rio weight n=100 

# shift n@v2 to 50% of traffic gradually over 5m
rio weight --duration=5m n@v2=50 

# Pause last command at current state, will pause all rollouts on versions in app
rio weight --pause=true n@v2=50