Skip to content
This repository has been archived by the owner on Sep 5, 2024. It is now read-only.

Latest commit

 

History

History
906 lines (632 loc) · 38.3 KB

cli-reference.md

File metadata and controls

906 lines (632 loc) · 38.3 KB
Raw

CLI Reference

Table of Contents

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