# vpctl architecture and security

> Learn about vpctl trust boundaries, three usage modes, and what vpctl touches on the network and in your cluster.

This page helps security teams review vpctl. It describes what vpctl touches on the network, in your cluster, and on disk. It also shows the three usage modes in this guide. Each mode has different trust-boundary implications, you can pick the one that matches your security posture.

## What vpctl does (full capability map)

vpctl spans five phases. Only **Render** (`release generate`) is a required phase, every other phase is optional and can be replaced by your existing tooling. The three usage modes that follow are common combinations of these phases.

![vpctl capability map](/api/media?file=/cloud/media/images/vpctl-capability-map.png)

The following are the three usage modes:

* Mode A (recommended) uses every phase.
* Mode B is Mode A with the Mirror phase made explicit for air-gapped deployments.
* Mode C uses only Render and stops there, vpctl hands outputs to the CD tooling you already run.

## Mode A — Recommended (CI + ArgoCD)

vpctl runs only in your CI pipeline. Your `manifest.yaml` lives in your Git repo, typically the same repo ArgoCD reads from, or a sibling repo your CI checks out. The pipeline does the following:

* Checks out the manifest
* Pulls the release from the Unity registry
  -Optionally mirrors artifacts to your registry
* Renders charts and Secret manifests
* Applies a single bootstrap ArgoCD `Application` to the cluster.
  After that, ArgoCD pulls charts from your Git repo and deploys workloads. With `--format argocd` (recommended), vpctl never holds a cluster-wide deploy credentials. Argo CD manages those credentials instead.. In this mode, the `--format helm` variant requires the CI runner to use a cluster-wide kubeconfig.

![Mode A — recommended CI + ArgoCD](/api/media?file=/cloud/media/images/vpctl-mode-a.png)

Step 7 supports two formats:

1. With `--format argocd` (recommended), vpctl applies a single bootstrap `argoproj.io/Application` and ArgoCD pulls from Git after that. vpctl's cluster touch is limited to two namespace-scoped applies (Secrets + the Application).
2. With `--format helm`, vpctl runs `helm upgrade --install` for every chart in the release, which requires a cluster-wide kubeconfig in the CI runner. ArgoCD is recommended because it keeps the cluster-wide deployment credentials out of CI.

## Mode B — Air-gapped mirror

A bastion or staging host, runs vpctl once to mirror Unity release artifacts into your private registry. After the mirror completes, the production cluster, Argo CD, and your Git repository no longer reach the public internet. Image references in the rendered charts are rewritten to your registry at generate time.

![Mode B — air-gapped mirror](/api/media?file=/cloud/media/images/vpctl-mode-b.png)

Only the bastion contacts the Unity registry, and only during sync time. After the sync completes, the deployment is fully internal. Same `--format helm | argocd` choice as Mode A; ArgoCD recommended.

## Mode C — Generate-only (bring your own CD)

vpctl renders Helm chart values and Kubernetes `Secret` manifests from your `manifest.yaml` and the extracted release package, and  then stops. Whatever CD tooling you already use — `helm`, `kubectl`, Flux, or custom pipelines can apply `generated-charts/` and `secrets.yaml`. vpctl never holds a kubeconfig in this mode and never reaches your cluster. This is the minimum viable use of vpctl.

![Mode C — generate-only](/api/media?file=/cloud/media/images/vpctl-mode-c.png)

vpctl also supports direct Helm deploy via `vpctl release deploy --format helm`, for more information, refer to [Other ways to use vpctl](#). It doesn't have a separate architecture diagram because it wraps `helm upgrade --install`.

## What vpctl touches

* **Outbound network**:
  * Unity registry (`uccmpprivatecloud.azurecr.io`) — required for `release pull` and the source side of `artifact sync`.
  * Your registry — required for the target side of `artifact sync`.
  * Kubernetes API — used only for `secret deploy` and `release deploy`.
* **Credentials read**:
  * Unity registry credentials, stored under your home directory after `vpctl configure`.
  * Docker credential store (`~/.docker/config.json`) for ORAS and OCI Helm operations.
  * kubeconfig (default discovery; override with `--context` on `secret deploy` and `release deploy`).
* **Files written** (inside the working directory only):
  * `extracted-release/` — release archive contents.
  * `generated-charts/` — rendered Helm charts and ArgoCD `Application` manifests.
  * `secrets.yaml` — rendered Kubernetes `Secret` manifests.
  * `secrets.import.yaml` — created only when you pass `--persist` to `secret generate`.
* **What vpctl never does**: send telemetry, call back to Unity, auto-update, or modify anything outside the working directory.