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¶
```shell script 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
```shell script
# 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¶
```shell script
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
```shell script
# 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¶
```shell script
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
```shell script
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¶
```shell script
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
```shell script
# 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¶
```shell script 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](install.md) 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](https://kubernetes.io/docs/tasks/access-application-cluster/create-external-load-balancer/) that points to API gateway.
Note: If service loadbalancer cannot be provisioned, [Nodeport](https://kubernetes.io/docs/concepts/services-networking/service/#nodeport) is used to expose API gateway.
##### Examples
```shell script
# 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¶
```shell script
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
```shell script
# 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¶
```shell script
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
```shell script
# 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¶
```shell script
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
```shell script
# 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: |
|
| --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¶
```shell script
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
```shell script
# 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¶
```shell script 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
```shell script
# 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¶
```shell script 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
```shell script
# 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¶
```shell script
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 ```