​
GitOps: Modern Kubernetes Cluster Management with Ankra

Welcome to the next-generation GitOps approach for managing Kubernetes clusters with Ankra. This guide walks you through setting up a scalable repository structure, integrating with Ankra’s WebUI, and leveraging AI-powered configuration tools.
A well-structured GitOps repository unlocks automation, reproducibility, and seamless collaboration for your platform engineering and DevOps teams.

​
Repository Structure: The Foundation

Organize your repository around a clusters/ directory. Each cluster gets its own folder, named to match its Ankra identity (e.g., prod-cluster-6chysytvjq/). Inside each cluster folder, you’ll find:

Add-ons

Direct Helm chart configurations for your cluster’s services.

Manifests

Raw Kubernetes YAML files for custom resources and infrastructure.

ArgoCD

GitOps workflows and advanced deployment strategies.

Cluster Definition

The main YAML file describing your cluster, stacks, and dependencies.

​
How Ankra Integrates With Your Repo

Ankra reads your cluster definition YAML (apiVersion: v1, kind: ImportCluster) and syncs with your Git repository. The platform automatically detects stacks, dependencies, and configuration files, then visualizes and manages them in the WebUI.
  • Stack-Based Architecture: Stacks group related services and control deployment order. Dependencies are resolved automatically.
  • Git Integration: Specify provider, credentials, branch, and repo in your YAML. Ankra keeps your clusters in sync with Git.
  • WebUI Experience: Use Stack Builder to visually manage stacks, dependencies, and resources. Drag, drop, and edit with instant feedback.

​
How DevOps and Developers Use Single YAML Cluster Stacks

DevOps

  • Build and maintain cluster stacks with best practices, security, and compliance baked in.
  • Update stacks as requirements change, and manage them through pull requests and code reviews.

CI/CD Pipelines

  • Automate cluster creation, updates, and rollbacks as part of your software delivery process.
  • Every change is tracked and auditable.

Developers

  • Instantly spin up consistent, production-like environments for development, testing, or demos.
  • No more “it works on my machine” problems. Just point to the right YAML file and go.

​
Stack Builder & AI Editor: Your Modern Toolset

Visual Stack Builder

Instantly see and edit your cluster’s architecture. Drag-and-drop to reorganize stacks, set dependencies, and preview changes before deploying.

AI Editor

Get intelligent suggestions for Helm upgrades, best practices, and security improvements. The AI editor validates YAML, resolves dependencies, and flags issues in real time.

​
Workflow: From Repo to Running Clusters

  1. Create your GitHub repository and connect it to Ankra.
  2. Add your clusters: Create folders, add manifests, add-ons, and cluster definition YAMLs.
  3. Configure stacks and dependencies visually in Stack Builder.
  4. Leverage the AI editor for validation and optimization.
  5. Preview, validate, and deploy—all from the WebUI.
  6. Monitor deployments and cluster state in real time.

​
Impact: What Happens When You Commit

  • Ankra reads your changes, deploys stacks in the correct order, and maintains your cluster’s desired state.
  • Multi-cluster support lets you manage dev, staging, and prod from a single repo.
  • Rollbacks, drift detection, and cross-cluster dependencies are handled automatically.

​
Best Practices

​
Troubleshooting

​
Example: Modern Cluster Repo

clusters/
  prod-cluster-6chysytvjq/
    add-ons/
    manifests/
    argocd/
    prod-cluster.yaml
  dev-cluster-134pmgb2lw/
    add-ons/
    manifests/
    argocd/
    dev-cluster.yaml

apiVersion: v1
kind: ImportCluster
metadata:
  name: prod-cluster-6chysytvjq
spec:
  git_repository:
    provider: github
    credential_name: User-CodeStaple
    branch: main
    repository: CodeStaple/cluster-repo
  stacks:
    # Define stacks and dependencies here
Pro Tip: This approach streamlines the entire software lifecycle, from development to production. It makes it easy to reproduce, update, and manage clusters at every stage.

​
YAML Breakdown: Cluster Definition

Key/PathDescription
apiVersion: v1Specifies the API version for the resource.
kind: ImportClusterDeclares the type of resource to create (an imported cluster).
metadata.nameThe name of your cluster (matches directory name).
spec.git_repository.providerThe Git provider (e.g., github, gitlab).
spec.git_repository.credential_nameThe credential to use for accessing the repo.
spec.git_repository.branchThe branch to watch for changes.
spec.git_repository.repositoryThe repository path (org/repo).
spec.stacksList of stacks to deploy to the cluster.
stacks[].nameName of the stack.
stacks[].descriptionDescription of the stack.
stacks[].manifestsList of manifests to apply.
manifests[].nameName of the manifest.
manifests[].manifest_base64The manifest YAML, base64-encoded.
manifests[].namespaceNamespace for the manifest.
manifests[].parentsDependencies for this manifest.
stacks[].addonsList of add-ons to install.
addons[].nameName of the add-on.
addons[].chart_nameHelm chart name for the add-on.
addons[].chart_versionVersion of the Helm chart.
addons[].repository_urlURL of the Helm chart repository.
addons[].namespaceNamespace for the add-on.
addons[].configuration_typeHow the add-on is configured (e.g., standalone).
addons[].configuration.values_base64Helm values.yaml, base64-encoded.
addons[].parentsDependencies for this add-on.
Use Stack Builder and AI editor in Ankra’s WebUI to visually configure, validate, and optimize your cluster setups.

​
Understanding the ArgoCD Folder

Each cluster directory contains an argocd/ folder, used by ArgoCD for managing application deployments and syncing resources.
Important: The files in the argocd/ folder are auto-generated by Ankra and will be overwritten on each sync or update. Any manual changes made here will not persist.
The true source of your cluster configuration is always the add-ons/ and manifests/ folders, along with your cluster definition YAML. To make lasting changes, update your Helm values in add-ons/, your manifests in manifests/, or your cluster YAML, never directly in argocd/.

​
Writing a Cluster YAML: Referencing Manifests and Helm Values

Ankra supports referencing external files in your cluster YAML using the from_file key. This makes your configuration modular, readable, and easy to maintain.

​
Example Structure

apiVersion: v1
kind: ImportCluster
metadata:
  name: prod-cluster
  description: Your imported cluster
spec:
  git_repository:
    provider: github
    credential_name: User-CodeStaple
    branch: main
    repository: CodeStaple/addons2
  stacks:
    - name: infisical
      description: 'Secret management for the stack.'
      manifests:
        - name: infisical ns
          from_file: manifests/infisical ns.yaml
        - name: infisical secret
          parents:
            - name: infisical ns
              kind: manifest
          from_file: manifests/infisical secret.yaml
      addons:
        - name: infisical
          chart_name: infisical
          chart_version: 0.4.2
          repository_url: https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts
          namespace: infisical
          configuration_type: standalone
          configuration:
            from_file: add-ons/infisical/values.yaml

​
How from_file Works

Manifests:
  • Use from_file to reference Kubernetes YAML files (e.g., CRDs, RBAC, ConfigMaps) stored in your repo. This keeps your cluster definition clean and lets you reuse files across stacks.
Add-ons (Helm):
  • Use from_file under configuration to point to a Helm values.yaml file. This allows you to customize Helm charts without embedding large YAML blocks directly in your cluster definition.

​
Example: ingress-nginx values.yaml

controller:
  ingressClassResource:
    enabled: true
  service:
    type: NodePort
    nodePorts:
      http: "30080"
      https: "30443"
Referenced in your cluster YAML as: 
addons:
  - name: ingress-nginx
    chart_name: ingress-nginx
    chart_version: 4.12.3
    repository_url: https://kubernetes.github.io/ingress-nginx
    namespace: ingress-nginx
    configuration_type: standalone
    configuration:
      from_file: add-ons/ingress-nginx/values.yaml

​
Example: Manifest File

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: local-path-provisioner-role
rules:
  - apiGroups: [""]
    resources: ["nodes", "persistentvolumeclaims", "configmaps", "pods", "pods/log"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch", "create", "patch", "update", "delete"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "patch"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]
Referenced in your cluster YAML as: 
manifests:
  - name: local-path-provisioner-role
    from_file: manifests/clusterRole: local-path-storage.yaml

CI/CD Automation

Trigger cluster changes automatically from your Git repository. Every commit can update your cluster, making continuous delivery simple and reliable.

On-Demand Environments

Spin up new clusters or restore existing ones instantly. With everything in one file, you can reproduce environments for testing, staging, or disaster recovery.

Great Reproducibility & Audit

Keep a full history of every change. Roll back, audit, or share your cluster setup with confidence. Your YAML file is the single source of truth.