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 aclusters/
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
- Create your GitHub repository and connect it to Ankra.
- Add your clusters: Create folders, add manifests, add-ons, and cluster definition YAMLs.
- Configure stacks and dependencies visually in Stack Builder.
- Leverage the AI editor for validation and optimization.
- Preview, validate, and deploy—all from the WebUI.
- 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
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/Path | Description |
---|---|
apiVersion: v1 | Specifies the API version for the resource. |
kind: ImportCluster | Declares the type of resource to create (an imported cluster). |
metadata.name | The name of your cluster (matches directory name). |
spec.git_repository.provider | The Git provider (e.g., github, gitlab). |
spec.git_repository.credential_name | The credential to use for accessing the repo. |
spec.git_repository.branch | The branch to watch for changes. |
spec.git_repository.repository | The repository path (org/repo). |
spec.stacks | List of stacks to deploy to the cluster. |
stacks[].name | Name of the stack. |
stacks[].description | Description of the stack. |
stacks[].manifests | List of manifests to apply. |
manifests[].name | Name of the manifest. |
manifests[].manifest_base64 | The manifest YAML, base64-encoded. |
manifests[].namespace | Namespace for the manifest. |
manifests[].parents | Dependencies for this manifest. |
stacks[].addons | List of add-ons to install. |
addons[].name | Name of the add-on. |
addons[].chart_name | Helm chart name for the add-on. |
addons[].chart_version | Version of the Helm chart. |
addons[].repository_url | URL of the Helm chart repository. |
addons[].namespace | Namespace for the add-on. |
addons[].configuration_type | How the add-on is configured (e.g., standalone). |
addons[].configuration.values_base64 | Helm values.yaml, base64-encoded. |
addons[].parents | Dependencies 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 anargocd/
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.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 thefrom_file
key. This makes your configuration modular, readable, and easy to maintain.
Example Structure
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.
- Use
from_file
underconfiguration
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
Example: Manifest File
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.