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
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 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"