Kubernetes Install

This guide walks through installing the Apoxy controller into a Kubernetes cluster. Use this path when your source of truth for Gateway API resources lives in Kubernetes.

Install the controller

apoxy k8s install fetches the onboarding manifests from the Apoxy API and applies them to your target cluster:

apoxy k8s install \
  --context <kube-context> \
  --namespace apoxy \
  --cluster-name <cluster-name> \
  --mirror gateway \
  --yes

Available flags

• --kubeconfig — Explicit kubeconfig path.
• --dry-run — Print the manifests without applying them.
• --force — Force overwrite conflicting fields during apply.
• --image — Override the controller image embedded in the onboarding manifests.
• --yes — Skip interactive confirmation.

Your first install

Authenticate and install the controller:

apoxy auth login
apoxy k8s install \
  --context prod-us-west-2 \
  --namespace apoxy \
  --cluster-name prod-us-west-2 \
  --mirror gateway

During installation, the CLI resolves your kubeconfig and context, requests onboarding manifests from the Apoxy API, and applies resources into the target namespace. On subsequent runs, if you omit --cluster-name, the CLI recovers it from the namespace annotation apoxy.dev/cluster-name.

Mirror mode

The --mirror flag controls which resource types the controller mirrors to Apoxy:

• gateway — Mirror Gateway API resources. Use this when Gateway API is your primary routing configuration.
• ingress — Mirror Ingress resources. Use this when you're bridging existing Ingress workflows.
• all — Mirror both Gateway API and Ingress resources.

Preview with dry-run

Before applying to a cluster, preview the manifests:

apoxy k8s install \
  --context dev-cluster \
  --namespace apoxy \
  --cluster-name dev-cluster \
  --mirror gateway \
  --dry-run

Verify the install

After installing, confirm these basics:

• The kubeconfig path resolves to the cluster you intended.
• The selected context matches the target cluster.
• The namespace is correct.
• The Apoxy CLI is authenticated (apoxy auth login).
• The project selection in your CLI config matches the target environment.

Common errors

• failed to load kubeconfig — Bad kubeconfig path or incorrect current context.
• failed to get YAML — Authentication issue or API-side onboarding problem.
• Apply conflicts — Use --force only when you understand the field ownership implications.
• Non-interactive runs without --yes — The CLI requires confirmation by default.

Updating the install

Re-run apoxy k8s install when you need to:

• Change the mirror mode.
• Switch to a custom controller image.
• Pick up updated onboarding manifests from Apoxy.

Use --cluster-name explicitly in automation so the intended cluster identity is always clear.