LogoLogo
  • Welcome to Release
  • Getting started
    • Quickstart
    • Create an account
    • Prepare to use Release
    • Create an application
      • Create custom application
      • Create from template
      • Servers vs runnables
    • Create an environment
  • Guides and examples
    • Domains and DNS
      • Manage domains
      • DNS and nameservers
        • Configure GoDaddy
        • Configure Cloudflare
        • Configure Namecheap
        • Other DNS hosts
      • Routing traffic
    • Example applications
      • Full stack voting app
      • Flask and RDS counter app
      • Static site with Gatsby
      • Golang with Postgres and Nginx
      • WordPress with MySQL
      • Spring and PostgreSQL
      • Terraform and Flask
      • OpenTelemetry demo
      • Load balancer with hostname
      • Static JavaScript service
      • SSH bastion access to services
      • ngrok and OAuth for private tunnels
      • Using OAuth Proxy
      • Hybrid Docker and static site
      • App Imports: Connecting two applications
      • Example library
    • Running instances
      • Cron jobs
      • Jobs
      • Using Helm charts
      • Using terminal
      • Viewing logs
      • Troubleshooting
        • ImagePullBackoff error
        • CrashLoopBackoff error
        • Exit codes
        • OOM: out of memory
    • Advanced guides
      • Containers guide
      • Application guide
      • Kubernetes guide
      • Create a cluster
      • Upgrade a cluster
      • Managing node groups
      • Patch node groups
      • Hostnames and rules
      • Serve traffic on multiple ports
      • Configure access to your K8s cluster
      • Designing for multiple environments
      • Microservices architecture
      • Monitoring your clusters
      • Performance tuning
      • Visibility and monitoring
      • Working with data
        • Container-based data
        • Seeding and migration
        • Cloud-provided data
        • Golden images
        • Third party
      • Pausing Instant Datasets
        • Application pausing schedules
        • Pause/resume environments
      • Infrastructure as code
        • Terraform
  • Reference documentation
    • Account settings
      • Account info
      • Managing users
      • Build settings
        • Build arguments
        • Build SSH keys
      • Add integrations
      • View clusters and cloud integrations
      • Add datasets
      • Environment handles
    • Workflows in Release
      • Stages of workflows
      • Serial deployments
      • Parallel deployments
      • Rolling deployments
      • Rainbow deployments
    • Networking
      • Network architecture (AWS)
      • Network architecture (GCP)
      • Ingresses
      • IP addresses
      • Cloud-provided services
      • Third-party services
    • Release environment versioning
    • Application settings
      • Application Template
        • Schema definition
      • Default environment variables
      • GitHub
      • Pull requests
      • GitOps
      • Just-in-time file mounts
      • Primary App Link
      • Create application FAQ
      • App-level build arguments
      • Parameters
      • Workspaces
    • End-to-end testing
    • Environment settings
      • Environment configuration
      • Environment variables
        • Environment variable mappings
        • Secrets vaults
        • Using Secrets with GitOps
        • Kubernetes Secrets as environment variables
        • Managing legacy Release Secrets
    • Environment expiration
    • Environment presets
    • Instant datasets on AWS
    • Instant datasets on GCP
    • Instant dataset tasks
      • Tonic Cloud
      • Tonic On-Premise
    • Cloud resources
    • Static service deployment
    • Helm
      • Getting started
      • Version-controlled Helm charts
      • Open-source charts
      • Building Docker images
      • Ingress and networking
      • Configuration
    • GitOps
    • The .release.yaml file
    • Docker Compose conversion support
    • Reference examples
      • Adding and removing services
      • Managing service resources
      • Adding database containers to the Application Template
      • Stock Off-The-Shelf Examples
    • Release API
      • Account Authentication
      • Environments API
        • Create
        • Get
        • Setup
        • Patch
      • User Authentication
      • Environment Presets API
        • Get Environment Preset List
        • Get Environment Preset
        • Put Environment Preset
  • Background concepts
    • How Release works
  • Frequently asked questions
    • Release FAQ
    • AWS FAQ
    • Docker FAQ
    • JavaScript FAQ
  • Integrations
    • Integrations overview
      • Artifactory integration
      • Cloud integrations (AWS)
        • AWS guides
        • Grant access to AWS resources
        • AWS how to increase EIP quota
        • Control your EKS fleet with systems manager
        • Managing STS access
        • AWS Permissions Boundaries
        • Private ECR Repositories
        • Using an Existing AWS VPC
        • Using an Existing EKS Cluster
      • Docker Hub integration
      • LaunchDarkly integration
      • Private registries
      • Slack integration
      • Cloud integrations (GCP)
        • GCP Permissions Boundary
      • Datadog Agent
      • Doppler Secrets Manager
      • AWS Secrets Management
    • Source control integrations
      • GitHub
        • Pull request comments
        • Pull request labels
        • GitHub deployments
        • GitHub statuses
        • Remove GitHub integration
      • Bitbucket
      • GitLab
    • Monitoring and logging add-ons
      • Datadog
      • New Relic
      • ELK (Elasticsearch, Logstash, and Kibana)
  • Release Delivery
    • Create new customer integration
    • Delivery guide
    • Release to customer account access controls
    • Delivery FAQs
  • Release Instant Datasets
    • Introduction
    • Quickstart
    • Security
      • AWS Instant Dataset security
    • FAQ
    • API
  • CLI
    • Getting started
    • Installation
    • Configuration
    • CLI usage example
    • Remote development environments
    • Command reference
      • release accounts
        • release accounts list
        • release accounts select
      • release ai
        • release ai chat
        • release ai config-delete
        • release ai config-init
        • release ai config-select
        • release ai config-upsert
      • release apps
        • release apps list
        • release apps select
      • release auth
        • release auth login
        • release auth logout
      • release builds
        • release builds create
      • release clusters
        • release clusters exec
        • release clusters kubeconfig
        • release clusters shell
      • release datasets
        • release datasets list
        • release datasets refresh
      • release deploys
        • release deploys create
        • release deploys list
      • release development
        • release development logs
        • release development start
      • release environments
        • release environments config-get
        • release environments config-set
        • release environments create
        • release environments delete
        • release environments get
        • release environments list
        • release environments vars-get
      • release gitops
        • release gitops init
        • release gitops validate
      • release instances
        • release instances exec
        • release instances logs
        • release instances terminal
  • Release.ai
    • Release.ai Introduction
    • Getting Started
    • Release.ai Templates
    • Template Configuration Basics
    • Using GPU Resources
    • Custom Workflows
    • Fine Tuning LlamaX
    • Serving Inference
Powered by GitBook
On this page
  • Overview
  • Creating an environment
  • Interacting with instances
  • Interacting directly with an underlying cluster
  • Streamlining Release configuration via GitOps
  • Deleting an environment

Was this helpful?

  1. CLI

CLI usage example

PreviousConfigurationNextRemote development environments

Last updated 1 year ago

Was this helpful?

Overview

We can use the Release CLI to create, manage, and interact with ephemeral environments. The example voting application is a Dockerized application that contains three services: Vote, Result, and Worker, along with a Postgres database and Redis. We can use it to illustrate how to work with the Release CLI.

To get started using Release CLI, make sure you have a and have worked through the .

Get , and follow the .

Creating an environment

By using the release environments create command, we can spin up an environment from the Release CLI. This is often used in automation tasks in CI to create ephemeral environments programmatically.

If we have configured our application correctly in the above step, we should be able to list all our applications using release apps list:

% release apps list
ID    NAME
1921  example-voting-app-1

Note: The ID and NAME of an application can be used interchangeably in commands that require the --app flag.

As arguments to the create command, we pass in the app we want to deploy, the branch we want to track related to that application, and optionally any image overrides that are present.

We can also provide the --wait flag, which specifies that the command should wait for the deployment of the environment to complete before exiting. Additionally, the --verbose flag can be used to give us more detailed log output.

Before creating an environment for an application, we need to ensure that we have configured it to be able to be built automatically, or we need to have manually created a build for the branch we want to specify, through the UI.

% release environments create --app example-voting-app-1 --branch main --wait --verbose
2022/05/20 00:01:20 Task [1526048] started as part of Task Chain [421859]!
2022/05/20 00:01:21 Task [1526047] started as part of Task Chain [421859]!
2022/05/20 00:01:22 Applying: registry-secrets
2022/05/20 00:01:22 Applying: example-voting-app-1-ingress
2022/05/20 00:01:22 Creating example-voting-app-1-ingress.
...
2022/05/20 00:03:06 Task Chain [421858] done as part of Pipeline Stage [511267]! End State is [done]!
2022/05/20 00:03:06 SpaceStage [511267] finished successfully as part of Space Pipeline [153125]!
2022/05/20 00:03:06 Space Pipeline [153125] finished successfully!
Created Environment: 36470
Created Deploy: 153125

Once we’ve run the command, it will create the environment and wait for the deployment. We should see output from the build and deploy logs in our terminal. This output replicates what we might see in the Release UI under the environment deploys page.

We can also optionally provide the -o json flag to the above command, so that the command output is JSON formatted. This is useful in CI and automation tasks.

We can now list the environments for our app with the environments list command:

% release environments list --app example-voting-app-1
ID     HANDLE   NAME                 STATE     BRANCH  TYPE       VERSION  LAST DEPLOYED         EXPIRES
36470  tede739  awesome-release-main  deployed  main ephemeral  v2.1     2022-05-19T22:02:48Z  2022-05-26T22:02:48Z

Additionally, we can view the deploys for our environment using the release deploys list command. This command gives us the details of the deploy that was initiated when our environment was created, including how long it took, and the name of the environment it was against.

% release deploys list --app 1921
ID      NAME    ENV NAME             STATE  STARTED AT                         TOTAL DURATION
154371  Deploy  awesome-release-main    done   2022-05-23 17:54:25.366 +0000 UTC  1m55s

Interacting with instances

In a similar vein to the capabilities provided by the UI, the Release CLI lets us interact with the instances in an environment.

We can:

  • Stream logs from an instance deployed in an environment.

  • exec into a terminal in an instance to run commands in the container.

Using the environment we created in the above section, we can exec into a terminal in the pod our application is running in.

To exec into a terminal from the CLI, we can run the instances terminal command. This command automatically downloads the Kubernetes configuration for the environment to our development machine and sets us up with a terminal running whatever shell is installed on the pod.

release instances terminal --app backend

If we don’t specify an environment name, the Release CLI will provide a fuzzy search interactive prompt to allow us to select the environment we want.

Additionally, we will be prompted to choose the instance we want to create a terminal for.

After running the command, we should be able to interact with a shell running in the pod:

<shell output>

Similarly, we can stream logs from a pod by running the instances logs command:

release instances logs --app example-voting-app-1

This command will connect to the pod in a specific environment that corresponds to the app, and stream the logs to the terminal.

% release instances logs --app example-voting-app-1
vote-7d65b9959f-b255h/vote: * Serving Flask app "app" (lazy loading)
vote-7d65b9959f-b255h/vote: * Environment: production
vote-7d65b9959f-b255h/vote: WARNING: This is a development server. Do not use it in a production deployment.
vote-7d65b9959f-b255h/vote: Use a production WSGI server instead.
vote-7d65b9959f-b255h/vote: * Debug mode: on
vote-7d65b9959f-b255h/vote: * Running on http://0.0.0.0:80/ (Press CTRL+C to quit)
vote-7d65b9959f-b255h/vote: * Restarting with stat
vote-7d65b9959f-b255h/vote: * Debugger is active!
vote-7d65b9959f-b255h/vote: * Debugger PIN: 152-459-136
vote-7d65b9959f-b255h/vote: 10.8.108.167 - - [19/May/2022 22:02:58] "HEAD / HTTP/1.1" 200 -

Interacting directly with an underlying cluster

To use clusters commands, make sure you have configured a cluster in the Account Settings page of the Release UI.

Should we need to interact with the cluster, we can do this through the clusters exec command. The clusters exec command will run the provided Kubernetes client command with the following environment variables set:

  • KUBECONFIG, set to a temporary file containing the cluster's Kubernetes config.

  • AWS_ACCESS_KEY and AWS_SECRET_KEY, set to the credentials with access to the AWS account.

The command will download the configuration for the cluster and inject it locally through the above environment variables.

We can use clusters exec to run any Kubernetes client command that respects the above variables, such as kubectl, k9s, aws, and many others.

The temporary environment variables are cleaned up as soon as the command completes.

There are a few ways to specify the cluster you want to exec against:

  • We can specify the cluster context directly via the --cluster flag.

  • We can specify the --app and --environment flags. This will point to the cluster to the environment containing the app and set the Kubernetes namespace to the namespace containing the app, for example, release clusters exec --app backend --environment training -- kubectl get pods. This command tells the CLI to access the cluster the backend app is using in the training environment and run kubectl get pods.

A related command is clusters shell. Instead of running a provided command, this command will give us a new shell with the Kubernetes configuration set (the namespace and cluster for the environment). This allows us to run multiple commands against that cluster.

Exiting the created shell will clear the configuration in a similar way to the clusters exec command and return to the regular terminal.

Streamlining Release configuration via GitOps

This is still a relatively new feature. Should you wish to use gitops, please contact the Release team to have it enabled on your account. You can still commit and download the configuration, but the integration needs to be turned on.

We can use the release gitops commands to ease the process of migrating an application that was configured via the Release UI, but isn’t currently using GitOps.

By running the release gitops init command in an application's repo, we can automatically download the required configuration for the app. The following configuration files will be downloaded:

  • A .release.yaml file, containing the default configuration for the application.

  • A directory called .release/, containing the application template and environment variable configuration for the app.

% release gitops init --app example-voting-app-1

⣾ Downloading existing configs...
Copying existing application template to .release/application_template.yaml
⣽ Downloading existing configs...
Copying existing environment variables config to .release/environment_variables.yaml

When we update any of our configuration, we can ensure that it is sane and valid by running release gitops validate. The output of this command will inform us of any errors in the configuration, and make suggestions for how it can be fixed. This is especially useful if the Release CLI is being used as part of CI/CD, and we need to validate any configuration errors before running other commands. It's useful to set this up as a Git pre-commit hook to catch any errors up front.

% release gitops validate
⣟ Validating GitOps config...

✅ GitOps config is valid

Deleting an environment

Although ephemeral environments will automatically be deleted after a specific amount of time, we might want to delete an environment before then. To do this, we can use the environments delete command.

Run the following command, specifying the app (by ID or by name) and the environment you want to delete (by ID or by name).

% release environments delete --app example-voting-app-1 36470
⣾ Deleting environment...

In the above command, example-voting-app-1 is the name of the application, and 36470 is the ID of the environment we want to delete.

Release account
the code for the example voting application
guide to configure it as a Release application
CLI quickstart guide
Release UI Deployment
CLI environment search
CLI instance search