Define your whole cluster: configuration, manifests, and add-ons in a single YAML file. This makes it easy to automate deployments, trigger changes from CI/CD, and quickly spin up new environments when you need them.

When Should You Use a Single YAML File?

Use a single YAML file when you want everything about your cluster in one place:

  • Quickly spin up or tear down clusters for testing, demos, or development.
  • Keep your setup simple. If it fits in one file, this is the way to go.
  • Share or move your cluster definition between teams or environments.
  • Keep things portable and easy to version in Git.

Tip: If your project grows or you need more modularity, you can always switch to the multiple YAML (include paths) approach later.

What is a Single YAML GitOps File?

A single YAML GitOps file is just one file that describes everything your cluster needs: configuration, manifests, and add-ons. You keep it in your Git repo, and Ankra uses it to set up and manage your cluster. Usually, manifests and values are base64-encoded right in the file. This makes your setup easy to share, move, and keep in sync.

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.

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.

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.

Example: Single YAML Definition

apiVersion: v1
kind: ImportCluster
metadata:
  name: prod-cluster
  description: Production Kubernetes cluster
spec:
  git_repository:
    provider: github
    credential_name: User-CodeStaple
    branch: main
    repository: CodeStaple/addons2
  stacks:
  - name: infisical
    description: ''
    manifests:
    - name: infisical ns
      manifest_base64: <base64-encoded YAML>
      namespace: infisical
      parents: []
    - name: infisical secret
      manifest_base64: <base64-encoded YAML>
      namespace: infisical
      parents:
      - name: infisical ns
        kind: manifest
    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:
        values_base64: <base64-encoded values.yaml>
      parents:
      - name: infisical secret
        kind: manifest

YAML Breakdown

Line/KeyDescription
apiVersion: v1Specifies the API version for the resource.
kind: ImportClusterDeclares the type of resource to create (an imported cluster).
metadataMetadata about the cluster resource.
metadata.nameThe name of your cluster.
metadata.descriptionA human-readable description for your cluster.
specThe main specification for the cluster.
spec.git_repositoryDetails of the Git repository to sync from.
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.

How It Works

  • Ankra watches your Git repository for changes.
  • When you update your YAML file, Ankra automatically syncs your cluster to match the desired state.
  • You can use this approach for simple, portable, and fully reproducible cluster setups.

Tip: Use base64 encoding for manifest and values content in single YAML files to keep everything self-contained and portable.