> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> From first cluster to GitOps pipeline in minutes.

This guide walks you through the three stages of setting up Ankra: building your stack in the UI, connecting GitOps for automation, and using AI to manage your infrastructure.

***

## 1. Connect a Cluster

Everything starts with a cluster. Import an existing one or provision a new managed cluster.

<Tabs>
  <Tab title="Import Existing Cluster">
    Import any Kubernetes cluster — EKS, GKE, AKS, on-prem, k3s, minikube, or kind.

    <Steps>
      <Step title="Create the cluster in Ankra">
        Go to **Clusters** and click **Import Cluster**. Give it a name.
      </Step>

      <Step title="Install the Ankra agent">
        Ankra generates a Helm command for your cluster. Run it wherever you have `kubectl` access:

        ```bash theme={null}
        helm upgrade --install ankra-agent oci://ghcr.io/ankraio/ankra-agent/ankra-agent \
          --namespace ankra \
          --create-namespace \
          --set config.token="YOUR_UNIQUE_TOKEN"
        ```

        The agent connects your cluster to the platform securely. It works behind firewalls, NATs, and private networks.
      </Step>

      <Step title="Verify the connection">
        Your cluster appears in the dashboard within seconds. You now have full visibility into workloads, resources, and events.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Provision a Managed Cluster">
    Ankra provisions production-ready K3s clusters on Hetzner, OVHCloud, or UpCloud with automated networking, bastion hosts, and NAT gateways.

    <Steps>
      <Step title="Add cloud credentials">
        Go to **Credentials** and add your cloud provider API key (Hetzner, OVH, or UpCloud). Don't have a Hetzner account? [Sign up for Hetzner Cloud](https://www.hetzner.com/cloud) to get started.
      </Step>

      <Step title="Create a cluster">
        Go to **Clusters** → **Create Cluster**. Select your provider and configure:

        * **Region** — choose a datacenter location
        * **Node sizing** — control plane and worker node types
        * **Networking** — private network range and subnet
        * **Kubernetes version** — pick a supported K3s version
      </Step>

      <Step title="Wait for provisioning">
        Ankra provisions the infrastructure, installs K3s, configures networking, and connects the agent. The cluster is fully yours — if you disconnect from Ankra, everything keeps running on your cloud account.
      </Step>
    </Steps>

    <Tip>
      You can also provision clusters from the CLI: `ankra cluster hetzner create`, `ankra cluster ovh create`.
    </Tip>
  </Tab>
</Tabs>

***

## 2. Build Your Stack

A **Stack** is a collection of Helm charts, manifests, and variables that define your Kubernetes environment. Build stacks visually or with AI assistance.

<Steps>
  <Step title="Open the Stack Builder">
    Navigate to your cluster → **Stacks** → **Create Stack**. The visual canvas opens.
  </Step>

  <Step title="Add components">
    Click **+ Add** to compose your stack:

    * **Add-ons** — Helm charts like Prometheus, Grafana, NGINX Ingress, cert-manager
    * **Manifests** — custom Kubernetes YAML (namespaces, RBAC, ConfigMaps, CRDs)

    Drag components onto the canvas and connect them to define deployment order.
  </Step>

  <Step title="Or, use the AI Assistant">
    Press `⌘+J` and describe what you need:

    *"I need a monitoring stack with Prometheus, Grafana, and Loki for a production cluster with 30-day retention"*

    The AI recommends components, configurations, dependencies, and deployment order tailored to your cluster.
  </Step>

  <Step title="Configure and deploy">
    Click any component to edit its values. Use [variables](/concepts/variables) with `${{ ankra.variable_name }}` for environment-specific configuration. Click **Create Stack** to save and deploy.
  </Step>
</Steps>

<Note>
  Stacks can be cloned across clusters — replicate a stack from dev to staging to production. See [Clone a Stack](/guides/clone-stack).
</Note>

***

## 3. Connect GitOps

Connect a GitHub repository to version-control your stacks and enable automatic deployments. This is where Ankra integrates with your existing CI/CD.

<Steps>
  <Step title="Connect your repository">
    Go to your cluster → **Settings** → **Integration**. Select a GitHub credential (or add one) and choose the repository where Ankra will store your cluster configuration.

    Ankra installs ArgoCD and the GitOps engine on your cluster automatically.
  </Step>

  <Step title="Your stacks are now in Git">
    Every stack you build is exported as Helm values and manifests to your repository under `clusters/{cluster-name}/`. Changes in either direction sync automatically.
  </Step>

  <Step title="Wire up your CI/CD pipeline">
    Your existing CI pipeline can now deploy through Ankra:

    1. CI builds a container image and pushes to your registry
    2. CI commits the new image tag to the GitOps repo
    3. Ankra detects the change and deploys to your cluster

    ```mermaid theme={null}
    flowchart LR
        A[git push] --> B[CI builds image]
        B --> C[Update GitOps repo]
        C --> D[Ankra syncs cluster]
    ```

    See the [CI/CD Pipeline Guide](/guides/cicd-pipeline) for a full walkthrough with GitHub Actions.
  </Step>

  <Step title="Monitor sync status">
    Go to your cluster → **Settings** → **GitOps** to view sync status, history, and any errors. Every sync is tracked with commit SHA, trigger source, and timestamp.
  </Step>
</Steps>

### GitOps file format

For advanced setups, define your clusters declaratively using `include` paths to keep configuration modular:

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: my-cluster
spec:
  git_repository:
    provider: github
    credential_name: my-credential
    branch: main
    repository: my-org/infra-gitops
  stacks:
    - name: platform-stack
      manifests:
        - include: manifests/
      addons:
        - include: addons/
```

Different teams can own different YAML files in the same repo — no merge conflicts, no monolithic configs. The full schema is in the [ImportCluster YAML reference](/reference/importcluster).

***

## 4. Manage with AI

With your cluster connected and stacks deployed, Ankra's AI capabilities unlock powerful management and debugging workflows.

### Ask the AI anything

Press `⌘+J` from anywhere in the platform. The AI is page-aware — it automatically knows what you're looking at.

| You're viewing | What the AI already knows                                             |
| -------------- | --------------------------------------------------------------------- |
| A crashing pod | Its logs, events, manifest, resource usage, and parent deployment     |
| A deployment   | All replicas, rollout status, associated services, and recent changes |
| A stack        | Installed add-ons, Helm values, deployment history, and dependencies  |

**Try these:**

* *"Why is my pod crashing?"*
* *"Scale this deployment to 5 replicas"*
* *"What changed in the last hour that could cause 503 errors?"*
* *"Create a Redis stack with persistence enabled"*

### Enable proactive AI Insights

Navigate to **Organisation Settings** → **General** → toggle **Proactive AI Insights**. The AI continuously scans your clusters and surfaces issues with root cause analysis, remediation commands, and MTTR analytics before they become incidents.

### Set up alerts with AI analysis

Configure [alert rules](/guides/alerts) on your cluster. When alerts trigger, Ankra's AI automatically collects cluster data and generates structured incident reports with root cause, affected resources, and recommended actions.

***

## What's Next

<CardGroup cols={2}>
  <Card title="Build a Monitoring Stack" icon="chart-line" href="/guides/monitoring-stack">
    Deploy Prometheus, Grafana, and Loki with AI assistance.
  </Card>

  <Card title="CI/CD Pipeline" icon="code-branch" href="/guides/cicd-pipeline">
    Full walkthrough: connect app repos to Ankra GitOps with GitHub Actions.
  </Card>

  <Card title="AI Assistant" icon="robot" href="/platform/ai-assistant">
    Deep dive into AI-powered troubleshooting, stack building, and incident triangulation.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/integrations/ankra-cli">
    Manage clusters, chat with AI, clone stacks, and encrypt secrets from the terminal.
  </Card>

  <Card title="Variables & Secrets" icon="key" href="/concepts/variables">
    Parameterise your stacks with organisation, cluster, and stack-level variables.
  </Card>

  <Card title="Clone Clusters" icon="clone" href="/guides/clone-cluster">
    Replicate entire cluster configurations across environments.
  </Card>
</CardGroup>

***

Still have questions? [Join our Slack community](https://join.slack.com/t/ankra-community/shared_invite/zt-3a5rem8f8-cUho4epX2MoLT83bFf~VSA) and we'll help out.