# 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)

Mode A runs vpctl only in your CI pipeline. It has two variants, depending on what performs the actual workload deployment:

* **Mode A (ArgoCD variant) — recommended.** vpctl renders ArgoCD app-of-apps charts, commits them to Git, and applies a single bootstrap `Application` CRD to the cluster. ArgoCD takes over from there. vpctl never holds a cluster-wide deployment credential — ArgoCD does.
* **Mode A (Helm variant).** vpctl renders Helm charts and runs `helm upgrade --install` directly for every chart in the release. There's no Git commit and no ArgoCD. The CI runner needs a cluster-wide kubeconfig, which is a weaker trust boundary. Use this variant only if you don't run ArgoCD.

### Mode A (ArgoCD variant)

Your `manifest.yaml` lives in your Git repo, typically the same repo ArgoCD reads from. The pipeline does the following:

1. Checks out the manifest.

2. Pulls the release from the Unity registry.

3. Optionally mirrors artifacts to your registry.

4. Renders charts and Secret manifests.

5. Commits the rendered charts to Git.

6. Applies a single bootstrap ArgoCD `Application` to the cluster.

7. ArgoCD pulls charts from your Git repo and deploys workloads.

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

vpctl's cluster touch is limited to two namespace-scoped applies: the Secrets and the bootstrap `Application`. All workload deployment after step 7 in the diagram is ArgoCD pulling from Git. ArgoCD holds the cluster-wide deployment credential, not the CI runner.

### Mode A (Helm variant)

If you don't run ArgoCD, vpctl can deploy directly with Helm. Steps 5, 8, and 9 in the diagram from the ArgoCD variant don't apply because there's no Git commit and no ArgoCD reconcile. Step 7 becomes `release deploy --format helm`, which runs `helm upgrade --install` for every chart in the release.

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

vpctl runs every chart's `helm upgrade --install` from CI. The CI runner kubeconfig must have rights to deploy every chart in the release — cluster-wide, not namespace-scoped. ArgoCD is recommended because it keeps that credential 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)

If you want vpctl to run the Helm deploys itself with `vpctl release deploy --format helm`, that isn't Mode C — it's the Mode A (Helm variant) flow described previously, because vpctl then needs a kubeconfig with cluster-wide deploy rights. For the deploy flags, refer to the [release command reference](./commands/release.md).

## 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.