Using Uffizzi from the CLI

This guide explains common ways of using Uffizzi to manage ephemeral environments. It assumes that you have already installed the Uffizzi CLI.

If just want to run a few quick commands, you may want to start with one of the Quickstart Guides. Otherwise, this guide covers example usage not described in the quickstarts.

Configuring the CLI

You can configure the Uffizzi CLI using the config subcommand. The configuration is stored in ~/.config/uffizzi/config_default.json.

uffizzi config

Use the list subcommand to view the current configuration:

uffizzi config list

Set the value of the specified property, like project:

uffizzi config set project my-project-fwyt

Get the value of the specified property, like server:

uffizzi config get-value server

Creating and managing clusters

Cluster creation and workload deployments

Use the Uffizzi CLI to create environments from a local directory. When you create an environment, the Uffizzi CLI will update the kubeconfig file you specify with a cluster hostname and certificate you can use to connect, as well as, update your current context. Here we create a cluster with the Uffizzi CLI:

uffizzi cluster create my-cluster -k ~/.kube/config

Then apply the manifests from a local directory with kubectl:

kubectl apply -f manifests/

Alternately, we can create a cluster and apply the manifests in a single Uffizzi command:

uffizzi cluster create -n my-cluster -k ~/.kube/config -m manifests/

💡

Note that you can alternatively use kustomization.yaml files with kubectl or Chart.yaml and values.yaml files with the helm command.

To connect to an existing Uffizzi cluster, you can run the update-kubeconfig command with the name of the cluster you're targeting and the location of your kubeconfig file:

uffizzi cluster update-kubeconfig my-cluster -k ~/.kube/config

See the CLI Reference for how Uffizzi handles kubeconfig updates.

Accessing services created inside the cluster

If you are creating ingresses explicitly in your manifests without a specific IngressClass. Uffizzi will dynamically set a hostname for all such ingresses created inside the ephemeral cluster environment. The naming of the ingress follows the convention as follows

<ingress-name>-<virtual-namespace>-<virtual-cluster-name>.<host-namespace>.uclusters.app.uffizzi.com

This allows us to keep the let users have easy access to their services through the ingress while keeping a more deterministic naming convention for the hostname without any extra configuraiton required to set up the hostname.

Creating and managing dev clusters

Dev evnvironment creation and workload deployments

Use the Uffizzi CLI to create environments from a local directory (support for remote Chart repositories is coming soon). When you create an environment, the Uffizzi CLI will update the kubeconfig file you specify with a cluster hostname and certificate you can use to connect, as well as, update your current context. Here we create a cluster with the Uffizzi CLI:

uffizzi cluster create -n my-cluster -k ~/.kube/config --update-current-context

Then apply the manifests from a local directory with kubectl:

kubectl apply -f manifests/

Alternately, we can create a cluster and apply the manifests in a single Uffizzi command:

uffizzi cluster create -n my-cluster -k ~/.kube/config -m manifests/

To connect to an existing Uffizzi cluster, you can run the update-kubeconfig command with the name of the cluster you're targeting and the location of your kubeconfig file:

uffizzi cluster update-kubeconfig my-cluster -k ~/.kube/config

See the CLI Reference for how Uffizzi handles kubeconfig updates.

Accessing services created inside the cluster

<ingress-name>-<virtual-namespace>-<virtual-cluster-name>.<host-namespace>.uclusters.app.uffizzi.com

Creating and managing Docker Compose environments

Use the compose command to create an ephemeral environment from a Docker Compose configuration.

💡

Uffizzi supports a subset of the of the complete Compose specification (opens in a new tab). Uffizzi also requires some additional configuration that is not included in the Compose specification, most notably an ingress definition. See the Uffizzi Compose File Reference for more detail on what is required for your docker-compose.uffizzi.yml file. For help writing this file or for using it in CI pipelines to create pull request environments, see our CI guides.

Create a Docker Compose preview environment

In the following example, we pass a docker-compose.uffizzi.yml from our local development environment. This command will create a preview environment for this compose file in the default account and project.

uffizzi compose create docker-compose.uffizzi.yml

💡

The Uffizzi CLI does not build containers for you from your local environment even if your environment includes a DOCKERFILE. Instead, you should execute a build step first, and then add images in your Docker Compose configuration (i.e. use the image directive instead of the build directive). Typically the build step is done in you CI pipeline, e.g. GitHub Actions or GitLab CI. You can see examples here.

Add metadata labels

You can add metadata labels to any preview using the --set-labels option:

uffizzi compose create docker-compose.uffizzi.yml \
  --set-labels="github.repo=my_repo github.pull_request.number=23"

Using Uffizzi From the Dashboard