Skip to main content

Deploy lifecycle

note

Start on your provider's page — it walks you through the full deployment and links here for the shared steps. This page covers the lifecycle steps that are common across all NIC-managed providers: setting up a GitOps repository, storing credentials, running nic deploy, verifying the cluster, signing in for the first time, updating, and tearing down.

Provider-specific prerequisites, configuration, and cost notes are on each provider's page.

What every deployment includes​

Regardless of provider, when nic deploy finishes your cluster will have:

  • Automatic TLS for every service you publish (cert-manager + Let's Encrypt).
  • Single sign-on across all services (Keycloak).
  • Ingress routing for any service you expose (Envoy Gateway).
  • GitOps-driven updates: roll out or roll back apps by committing to your GitOps repo — ArgoCD reconciles the cluster to match (ArgoCD).

Each provider adds storage and cluster-type specifics — see the provider pages for details.

GitOps repository​

NIC uses GitOps: it commits ArgoCD app manifests to a Git repo you own and lets ArgoCD sync them into the cluster.

You'll need:

  1. A Git repo on any host reachable from the cluster (GitHub, GitLab, Bitbucket, self-hosted Gitea, etc.).

  2. A GitHub personal access token (GIT_TOKEN) scoped to the GitOps repo with Contents: read+write. Go to github.com/settings/tokens?type=beta, choose Only select repositories, pick your GitOps repo, and generate.

    For production, we recommend generating a second token (ARGOCD_GIT_TOKEN) with Contents: read-only, used by ArgoCD inside the cluster. If you skip it, ArgoCD will reuse GIT_TOKEN (which means the cluster has write access to your GitOps repo).

Secrets and credentials​

nic reads secrets from a .env file in the directory you run nic from (loaded via godotenv). See your provider's page for instructions on downloading the .env template.

Ensure .env is in your .gitignore before you commit anything:

# .gitignore
.env

Add your GitOps tokens to .env:

GIT_TOKEN=github_pat_...             # read+write, used by nic during deploy
ARGOCD_GIT_TOKEN=github_pat_...      # optional, read-only; used by ArgoCD to pull manifests

Configuration​

Download a starter config from your provider's page. For the full schema, see the NIC configuration reference.

Deploy​

From the directory containing your config file and .env:

# Quick syntax and shape check; no provider API calls.
nic validate -f <config-file>

# Validates config and credentials; no resources are created.
nic deploy -f <config-file> --dry-run

# Actually provision.
nic deploy -f <config-file>

If you need to extend the default timeout (large clusters, slow network), pass --timeout 1h.

DNS​

After deploy completes, your cluster needs a DNS record to be reachable:

  • Cloudflare-managed domains: add CLOUDFLARE_API_TOKEN to your .env with Zone:DNS:Edit permission on your domain's zone. nic creates the record automatically.
  • All other DNS providers: nic prints the load balancer's IP address or hostname at the end of deploy. Create an A/CNAME record at your DNS provider pointing your domain to that value. The cluster will not be reachable over HTTPS until the record propagates.

Verify​

note

The steps below use kubectl. Install it if you don't have it.

After setting KUBECONFIG (see your provider's page), check that the cluster is responsive:

kubectl get nodes
kubectl get pods -A

Then check the foundational ArgoCD applications are syncing:

kubectl get applications -n argocd

All ArgoCD applications should reach Healthy within a few minutes (some may briefly show Progressing or OutOfSync — this is normal).

tip

For an interactive view of all cluster resources (especially handy while watching ArgoCD apps sync), install k9s and run it after setting KUBECONFIG.

First sign-in​

nic does not create an end-user account, so create one in Keycloak before you can sign in:

  1. Get the Keycloak admin credentials: 
    kubectl -n keycloak get secret keycloak-admin-credentials -o json | jq '.data | map_values(@base64d)'
  2. Open https://keycloak.<your-domain>/auth/admin/ and sign in with those credentials.
  3. Switch the realm dropdown (top-left) from master to nebari.
  4. Go to Users → Add user, set a username and email, and save.
  5. On the user's Credentials tab, click Set password, enter one, and uncheck Temporary.
  6. Visit https://<your-domain> and sign in with the new user. You should land on the Launchpad.

Update an existing deployment​

To change something about a running cluster, edit your config and re-run:

nic deploy -f <config-file> --dry-run    # verify config resolves; no resources changed
nic deploy -f <config-file>              # apply it

nic is declarative, so only the diff is applied.

warning

Some config fields trigger destructive resource recreation when changed. Check your provider's page for which fields these are.

Destroy​

When you're done with the cluster, tear it down with nic destroy. Run a dry-run first to see what will be removed:

# Preview what will be destroyed.
nic destroy -f <config-file> --dry-run

# Tear down everything nic created.
nic destroy -f <config-file>

If a resource fails to delete and nic destroy exits with an error, retry with --force:

nic destroy -f <config-file> --force

Always confirm in your cloud provider's console that no orphan resources remain after destroy. See your provider's page for provider-specific cleanup notes.