Using Uffizzi¶

This guide explains key concepts and methods of using Uffizzi to manage ephemeral environments. It assumes that you have already installed the Uffizzi client.

If just want to run a few quick commands, you may want to start with the Quickstart Guide. Otherwise, this guide covers specific Uffizzi commands, and explains the most common ways that teams use Uffizzi: via the command-line (client) or a continuous integration (CI) pipeline.

Two Types of Ephemeral Environments¶

Uffizzi currently supports two types of ephemeral environments:

• (In Beta) Virtual Cluster environments are Kubernetes-based environments built from a Kubernetes specification—typically Helm Charts, kustomizations, or standard manifests applied by kubectl. You can read more about Uffizzi's virtual clusters here, but in short, these are fully functional Kubernetes clusters that run in isolation on top of a host cluster. Once you've created these clusters with the Uffizzi client or from your CI pipeline, you can use standard Kubernetes tools like kubectl and helm to manage them and their configurations.

• Docker Compose environments are container-based environments built from a Docker Compose specification. You can read more about Uffizzi's support for the Compose specification here, as well as a tutorial on how to configure a Uffizzi Compose file.

Managing Environments¶

Uffizzi has two primary functions:

1. Lifecycle Management - Uffizzi creates, updates and deletes your environments based on triggers. These triggers can be initiated manually, for example from the Uffizzi client, or via automated workflows like a CI pipeline.
2. Access Control - Uffizzi limits how your environments can be accessed and by whom. For example, Uffizzi enforces role-based access controls (RBAC) to limit who on your team can manage or update your environments, and allows you to password protect any environment's public URLs.

From the Uffizzi Client¶

Configuring the client¶

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

uffizzi config

Use the list subcommand to view the current configuration:

uffizzi config list

Set the value of the specified property, like username:

uffizzi config set username jdoe

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 client to create environments from a local directory (support for remote Chart repositories is coming soon). When you create an environment, the Uffizzi client 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 client:

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

Acessing 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 preview command to create an ephemeral environment from a Docker Compose configuration.

 
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 preview create docker-compose.uffizzi.yml

 
Add metadata labels

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

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

 
Add container registry credentials

If your compose file includes private images, you'll need to provide credentials so Uffizzi can pull these images and deploy them to your preview environment. Use the connect subcommand to add container registry credentials. See the CLI Refernce for a complete list of supported container registries.

For example, make Amazon ECR credentials available to all preview environments within the default project:

uffizzi connect ecr --registry https://my-account.dkr.ecr.us-west-2.amazonaws.com --id SOMEACCESSKEY --secret MYSUPERSECRETKEY

You can revoke these credential from Uffizzi with the disconnect subcommand:

uffizzi disconnect ecr

From a CI Pipeline¶

In addition to creating environments from the Uffizzi client, you can configure a CI service to automatically deploy new environments for certain events, like pull or merge requests.

GitHub Actions examples¶

Virtual cluster environment¶

Create a virtual cluster environment from a GitHub Actions workflow with the Uffizzi Cluster Action. This action creates/updates/deletes a Uffizzi virtual cluster every time a pull request is opened, updated, or closed.

Start by forking the quickstart-k8s repository on GitHub. Be sure to uncheck the option Copy the main branch only. This ensures that the try-uffizzi branch will be included in your fork.

Enable GitHub Actions workflows for your fork by selecting Actions, then select I understand my workflows, go ahead and enable them. GitHub Actions is free for public repositories.

Click to expand

 
Open a pull request for try-uffizzi branch against main in your fork. Be sure that you're opening a PR on the branches of your fork (i.e. your-account/main ← your-account/try-uffizzi). If you try to open a PR for UffizziCloud/main ← your-account/try-uffizzi, the Actions workflow will not run in this example.

 
What to expect

The PR will trigger a GitHub Actions workflow that uses the Uffizzi client and Kubernetes manifests to create a Uffizzi ephemeral environment for the microservices application defined by the repo. When the workflow completes, the ephemeral environment URL will be posted as a comment in your PR issue.

 
How it works

Ephemeral environments are configured with Kubernetes manifests that describe the application components and a GitHub Actions workflow that includes a series of jobs triggered by a pull_request event and subsequent push events:

1. Build and push the voting-app images
2. Create the Uffizzi cluster using the uffizzi-cli
3. Apply the Kubernetes manifests to deploy the application to the Uffizzi cluster
4. Delete the Ephemeral Environment when the PR is merged/closed or after

Docker Compose environment¶

Create a Docker Compose environment using the Preview Environments Action. This action creates/updates/deletes an ephemeral Docker Compose environment every time a pull request is opened, updated, or closed.

Start by forking the quickstart repository on GitHub. Be sure to uncheck the option Copy the main branch only. This ensures that the try-uffizzi branch will be included in your fork.

Click to expand

 
Enable GitHub Actions workflows for your fork by selecting Actions, then select I understand my workflows, go ahead and enable them. GitHub Actions is free for public repositories.

Click to expand

 
Open a pull request for try-uffizzi branch against main in your fork. Be sure that you're opening a PR on the branches of your fork (i.e. your-account/main ← your-account/try-uffizzi). If you try to open a PR for UffizziCloud/main ← your-account/try-uffizzi, the Actions workflow will not run in this example.

Click to expand

 
What To Expect

The PR will trigger a GitHub Actions workflow that creates a Uffizzi Ephemeral Environment for the microservices application defined by the repo. The environment URL will be posted as a comment in your PR issue when the workflow completes, along with a link to the Uffizzi Dashboard where you can view application logs. The environment and comment is deleted when the PR is merged/closed or after 1 hour (configurable).

 
How It Works

Previews are configured with a Docker Compose template that describes the application configuration and a GitHub Actions workflow that includes a series of jobs triggered by a pull_request event and subsequent push events:

1. Build and push images to a container registry
2. Render a Docker Compose file from the Docker Compose template and the built images
3. Deploy the application (per the Docker Compose file) to a Uffizzi Preview Environment and post a comment to the PR issue
4. Delete the Preview Environment when the PR is merged/closed or after 1h

Running this workflow will create a Uffizzi Cloud account and project from your GitHub user and repo information, respectively, if they do not already exits. If you sign in to the Uffizzi Dashboard you can view logs, password protect your previews, manage projects and team members, set role-based access controls, and configure single-sign on (SSO).

GitLab CI examples¶

Docker Compose environment¶

Create a Docker Compose environment from a GitLab CI pipleine.

Start by forking the the quickstart repository on GitLab. From the project home page, select Fork, then choose a namespace and project slug. Select Fork project.

Click to expand

---

 
Ensure GitLab CI/CD is enabled for your project. If you don't see the Build > Pipelines option in left sidebar, following these steps to enable it.

Click to expand

 
Open a merge request (MR) for try-uffizzi branch against master in your fork.

Be sure that you’re opening the MR on the branches of your fork (i.e. your-account/master ← your-account/try-uffizzi).

If you try to open a MR for uffizzi/quickstart/~/tree/master ← your-account/~/tree/try-uffizzi, the pipeline will not run in this example.

Click to expand

 
This will kick off a GitLab pipeline and the ephemeral environment URL will be dumped to stdout of the pipeline job.

 
What to expect

The MR will trigger a pipeline defined in .gitlab-ci.yml that creates a Uffizzi ephemeral environment for the microservices application defined by the repo. The ephemeral environment URL will be echoed to stdout of the deploy_environment Job. Look for the following line in the Job logs:

$ echo "Uffizzi Environment deployment details at URI:${UFFIZZI_CONTAINERS_URI}"
Uffizzi Environment deployment details at URI:https://app.uffizzi.com//projects/8526/deployments/27720/containers

This link will take you to the Uffizzi Dashboard where you can view application logs and manage your environments and team. The environment will be deleted when the MR is merged/closed or after 1 hour (configurable).

You might also want to configure a new Job to post the URL as a comment to your MR issue or send a notification to Slack, MS Teams, etc. See our Slack notification example here.

 
How it works

Ephemeral environments are configured with a Docker Compose template that describes the application components and a GitLab CI pipeline that includes a series of jobs triggered by a merge_request_event:

1. Build and push images to a container registry
2. Render a Docker Compose file from the Docker Compose template and the built images
3. Deploy the application to a Uffizzi ephemeral environment and echo the environment URL to the Job logs
4. Delete the environment

Running this workflow will create a Uffizzi Cloud account and project from your GitLab user and repo information, respectively. If you sign in to the Uffizzi Dashboard you can view logs, password protect your environments, manage projects and team members, set role-based access controls, and configure single-sign on (SSO).