Credentials - Ankra Platform

Credentials in Ankra store authentication information for connecting to external services like Helm registries, container registries, and Git providers. Credentials are securely stored and can be referenced when configuring integrations.

Credential Types

Registry Credentials

Authenticate with Helm chart registries (HTTP and OCI).

Git Credentials

Connect to GitHub, GitLab, and other Git providers.

Hetzner API Credentials

Authenticate with Hetzner Cloud for cluster provisioning.

OVH API Credentials

Authenticate with OVH Cloud for cluster provisioning.

AWS Credentials

Read-only IAM role or access keys for cloud cost estimates and inventory.

Google Cloud (GCP) Credentials

Read-only service account for cloud cost estimates and GKE discovery.

SSH Key Credentials

SSH keys for server access on provisioned clusters.

Registry Credentials

Registry credentials authenticate with Helm chart repositories. They’re used when syncing charts from private registries.

Creating a Registry Credential

Navigate to Credentials

Go to Credentials in the Ankra dashboard.

Add Credential

Click Add and select Registry as the provider type.

Enter Details

Name: A unique identifier (e.g., ghcr-auth, harbor-prod) Username: Your registry username Password: Your registry password or access token

Save

Click Create to securely store the credential.

Provider-Specific Setup

GitHub Container Registry (GHCR)

Create a Personal Access Token:

Go to GitHub → Settings → Developer settings → Personal access tokens
Generate a token with read:packages scope
For pushing charts, also add write:packages

Credential values: Username: Your GitHub username Password: The Personal Access Token

Google Artifact Registry

Create a Service Account:

Go to Google Cloud Console → IAM → Service Accounts
Create a new service account
Grant “Artifact Registry Reader” role
Create and download a JSON key

Credential values: Username: _json_key Password: The entire JSON key file contents

Amazon ECR

Get an auth token:

aws ecr get-login-password-region us-east-1

Credential values: Username: AWS Password: The token from the command above

ECR tokens expire after 12 hours. For production, consider using IAM roles or refresh the token regularly.

Azure Container Registry

Create a Service Principal:

az ad sp create-for-rbac-name ankra-acr-reader \
-scopes /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.ContainerRegistry/registries/{registry} \
-role acrpull

Credential values: Username: The appId from the output Password: The password from the output

Docker Hub

Create an Access Token:

Go to Docker Hub → Account Settings → Security
Create a new Access Token with Read permissions

Credential values: Username: Your Docker Hub username Password: The Access Token (not your password)

Harbor

Use a robot account (recommended):

Go to your Harbor project → Robot Accounts
Create a new robot account with pull permissions

Credential values: Username: robot$project+name (the robot account name) Password: The robot account secret

JFrog Artifactory

Create an API Key or Access Token:

Go to User Profile → Edit Profile
Generate an API Key or create an Access Token

Credential values: Username: Your Artifactory username Password: The API Key or Access Token

Hetzner API Credentials

Hetzner API credentials store your Hetzner Cloud API token, used when provisioning and managing Hetzner clusters. The token is validated against the Hetzner API on creation.

Don’t have a Hetzner account? Sign up for Hetzner Cloud to get started.

Creating a Hetzner API Credential

Get a Hetzner API Token

Log in to the Hetzner Console
Select your project
Go to Security → API Tokens
Click Generate API Token with Read & Write permissions
Copy the token (it’s only shown once)

Add to Ankra (UI)

Go to Credentials → Add → Hetzner, enter a name and paste your API token.

Or via CLI

ankra credentials hetzner create-name my-hetzner-token
# You will be securely prompted for the API token

Listing Hetzner Credentials

ankra credentials hetzner list

OVH API Credentials

OVH API credentials store your OVH Cloud application key, application secret, consumer key, and project ID used when provisioning and managing OVH clusters. The credentials are validated against the OVH API on creation.

Creating OVH API Credentials

Generate OVH API Credentials

Go to https://api.ovh.com/createToken/
Log in with your OVH account
Set the following permissions: GET, POST, PUT, DELETE on /cloud/project/* GET on /cloud/project
Click Create Keys
Save the Application Key, Application Secret, and Consumer Key

Get Your Project ID

Log in to the OVH Control Panel
Go to Public Cloud → select your project
Copy the Project ID from the dashboard URL or project settings

Add to Ankra (UI)

Go to Credentials → Add → OVH, enter a name, your project ID, and paste your API credentials.

Or via CLI

ankra credentials ovh create-name my-ovh-cred-project-id <project-id>
# You will be securely prompted for application key, application secret, and consumer key

Listing OVH Credentials

ankra credentials ovh list

AWS Credentials

AWS credentials let Ankra read your account to estimate the infrastructure cost of your clusters and sync cloud inventory. Access is read-only and cost-scoped — Ankra never provisions or modifies AWS resources. You can connect in one of two ways:

IAM role (recommended)

Ankra provides a CloudFormation “launch stack” link that creates a read-only role Ankra can assume, secured with a unique external ID. No long-lived keys to store or rotate.

Access keys

Provide an access key ID and secret for a read-only IAM user. Simpler to set up, but you own key rotation.

Creating an AWS Credential (IAM role)

Start onboarding

Go to Credentials → Add → AWS and choose the IAM role method. Ankra generates a unique external ID and a Launch stack link.

Launch the CloudFormation stack

Follow the launch-stack link into your AWS account. The template creates a read-only role scoped for cost, with a trust policy that only allows Ankra’s principal to assume it using your external ID.

Save the role

Copy the created role ARN back into Ankra and save. Ankra validates that it can assume the role before storing the credential.

Creating an AWS Credential (access keys)

Create a read-only IAM user

In AWS IAM, create a user (or use an existing one) with read-only access sufficient for pricing and inventory (for example, the AWS-managed ReadOnlyAccess/Billing policies, or a tighter custom policy).

Add to Ankra

Go to Credentials → Add → AWS → Access keys, enter a name, and paste the access key ID and secret access key.

Use the IAM role method where you can — it avoids storing long-lived secrets and is scoped and revocable on the AWS side by deleting the CloudFormation stack.

Google Cloud (GCP) Credentials

GCP credentials store a read-only service account key that Ankra uses to estimate the infrastructure cost of your clusters (and, in a future release, to discover GKE clusters). Ankra only ever reads from your project — it requests Google’s read-only OAuth scope and never provisions or modifies resources. The key is validated against the GCP Cloud Resource Manager API when you save it, so an invalid key or a project the service account can’t read is rejected immediately.

What Ankra Accesses

Ankra calls three Google APIs with the service account, all read-only:

API	Why it’s used
Cloud Resource Manager API	Verify the service account can read the project (the Test connection check)
Cloud Billing API	Read the public Compute Engine price catalog (SKUs) for cost estimates
Compute Engine API	Read machine-type specs (vCPU and memory) to price your nodes

Creating a GCP Credential

Enable the required APIs

In the Google Cloud Console, select your project and enable the Cloud Resource Manager API, Cloud Billing API, and Compute Engine API.Or with the gcloud CLI:

export PROJECT_ID="your-gcp-project-id"   # replace with your real project ID
gcloud config set project "$PROJECT_ID"

gcloud services enable \
  cloudresourcemanager.googleapis.com \
  cloudbilling.googleapis.com \
  compute.googleapis.com

Create a read-only service account

Go to IAM & Admin → Service Accounts → Create service account
Give it a name such as ankra-cost-readonly
Grant it the Viewer role (roles/viewer) on the project — or a custom read-only role

Or with gcloud (reusing the PROJECT_ID from the previous step):

gcloud iam service-accounts create ankra-cost-readonly \
  --display-name="Ankra cost (read-only)"

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/viewer"

If this fails with does not have permission to access projects instance [...:getIamPolicy] (or it may not exist), either PROJECT_ID is still set to the placeholder, or your account lacks the resourcemanager.projects.setIamPolicy permission. Confirm echo $PROJECT_ID shows your real project ID, and that you hold roles/owner or roles/resourcemanager.projectIamAdmin on it (otherwise ask a project admin to run this one command).

Create and download a JSON key

Open the service account → Keys → Add key → Create new key
Choose JSON and download the file

Or with gcloud:

gcloud iam service-accounts keys create ankra-key.json \
  --iam-account="ankra-cost-readonly@${PROJECT_ID}.iam.gserviceaccount.com"

The downloaded JSON must contain client_email, private_key, and token_uri.

Add to Ankra (UI)

Go to Credentials → Add → Google Cloud (GCP), then provide:Name: A unique identifier — lowercase letters and numbers only, cannot start with a hyphen (e.g. gcp-prod) Project ID: Your GCP project ID (e.g. acme-prod) Service Account Key (JSON): Paste the full contents of the downloaded key fileClick Test connection to verify access, then Add.

The service account only needs read access. Ankra requests Google’s cloud-platform.read-only scope, so even a more privileged key is used read-only.

Troubleshooting GCP Credentials

For gcloud setup errors during service-account creation (such as does not have permission ... (or it may not exist)), see the warning in the Create a read-only service account step above — it’s almost always an unsubstituted PROJECT_ID placeholder or a missing setIamPolicy permission. The table below covers the Test connection result in the Ankra UI:

Test connection result	Cause	Solution
The service account key is not valid JSON or is missing required fields	The pasted key isn’t the full JSON file	Paste the entire downloaded JSON; it must include `client_email`, `private_key`, and `token_uri`
Google rejected the service account credentials	The key is disabled or deleted	Confirm the key is active, or create a new JSON key
The service account lacks read access to this project	Missing IAM role or disabled API	Grant the Viewer role and enable the Cloud Resource Manager API
The project was not found	Wrong project ID	Check the Project ID matches your GCP project exactly
Could not reach the GCP Resource Manager API	Network or connectivity issue	Retry; ensure outbound access to `*.googleapis.com`

SSH Key Credentials

SSH key credentials store public keys that are deployed to servers during cluster provisioning. You can either provide your own public key or let Ankra generate a keypair for you.

Creating an SSH Key Credential

Choose an approach

Bring your own key: Provide an existing SSH public key Generate a keypair: Ankra generates a new Ed25519 keypair and returns the private key for you to save

Add to Ankra (UI)

Go to Credentials → Add → SSH Key, enter a name, and either paste your public key or choose Generate.

Or via CLI

# Generate a new keypair (via Hetzner credentials)
ankra credentials hetzner ssh-key create-name my-key-generate

# Generate a new keypair (via OVH credentials)
ankra credentials ovh ssh-key create-name my-key-generate

# Or provide your own public key
ankra credentials hetzner ssh-key create-name my-key \
-public-key "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5..."

When generating a keypair, the private key is only returned once. Save it immediately to a secure location.

Listing SSH Key Credentials

ankra credentials hetzner ssh-key list

Using Credentials

With Helm Registries

When adding a registry, select the credential to use for authentication:

Go to Charts → Repositories → Add
Enter the registry URL
Select the credential from the dropdown
Click Add

Ankra will use the credential when syncing charts from the registry.

With GitOps

Credentials are automatically used when syncing configurations to GitHub repositories connected via OAuth.

Managing Credentials

View Credentials

Go to Credentials to see all stored credentials:

Name and type
Creation date
Associated registries (if any)

Update a Credential

Click on the credential name
Update the username or password
Click Save

Updating a credential automatically applies to all registries using it. No need to reconfigure registries.

Delete a Credential

Go to Credentials
Click the menu (⋮) next to the credential
Select Delete

Deleting a credential will break authentication for any registries using it. Update those registries first.

Security

Storage

Credentials are stored securely using HashiCorp Vault:

Encrypted at rest
Access controlled per organization
Audit logging for all access

Best Practices

Use Tokens, Not Passwords

Prefer access tokens over account passwords. Tokens can be scoped and revoked independently.

Minimum Permissions

Grant only the permissions needed. For chart sync, read-only access is sufficient.

Rotate Regularly

Rotate credentials periodically, especially for production registries.

Separate by Environment

Use different credentials for dev, staging, and production registries.

Troubleshooting

Authentication Errors

Error	Cause	Solution
401 Unauthorized	Invalid credentials	Verify username and password/token
403 Forbidden	Insufficient permissions	Check the token has required scopes
Token expired	Temporary tokens (ECR)	Refresh the token
Connection refused	Network issue	Check firewall and network access

Common Issues

“unauthorized: authentication required”

The credential wasn’t selected when adding the registry
Edit the registry and select the correct credential

“invalid username/password”

The token may have been revoked or expired
Regenerate the token and update the credential

“permission denied”

The token doesn’t have read access to the repository
Update the token permissions or use a different account

API Access

Manage credentials via the Ankra API:

import requests

headers = {"Authorization": f"Bearer {TOKEN}"}

# List credentials
response = requests.get(
    "https://platform.ankra.app/api/v1/credentials",
    headers=headers
)

# Create credential
response = requests.post(
    "https://platform.ankra.app/api/v1/credentials",
    headers=headers,
    json={
        "name": "my-registry-auth",
        "provider": "registry",
        "username": "myuser",
        "password": "mytoken"
    }
)

See the API Reference for complete documentation.

​Credential Types

Registry Credentials

Git Credentials

Hetzner API Credentials

OVH API Credentials

AWS Credentials

Google Cloud (GCP) Credentials

SSH Key Credentials

​Registry Credentials

​Creating a Registry Credential

​Provider-Specific Setup

​Hetzner API Credentials

​Creating a Hetzner API Credential

​Listing Hetzner Credentials

​OVH API Credentials

​Creating OVH API Credentials

​Listing OVH Credentials

​AWS Credentials

IAM role (recommended)

Access keys

​Creating an AWS Credential (IAM role)

​Creating an AWS Credential (access keys)

​Google Cloud (GCP) Credentials

​What Ankra Accesses

​Creating a GCP Credential

​Troubleshooting GCP Credentials

​SSH Key Credentials

​Creating an SSH Key Credential

​Listing SSH Key Credentials

​Using Credentials

​With Helm Registries

​With GitOps

​Managing Credentials

​View Credentials

​Update a Credential

​Delete a Credential

​Security

​Storage

​Best Practices

Use Tokens, Not Passwords

Minimum Permissions

Rotate Regularly

Separate by Environment

​Troubleshooting

​Authentication Errors

​Common Issues

​API Access

Credential Types

Registry Credentials

Creating a Registry Credential

Provider-Specific Setup

Hetzner API Credentials

Creating a Hetzner API Credential

Listing Hetzner Credentials

OVH API Credentials

Creating OVH API Credentials

Listing OVH Credentials

AWS Credentials

Creating an AWS Credential (IAM role)

Creating an AWS Credential (access keys)

Google Cloud (GCP) Credentials

What Ankra Accesses

Creating a GCP Credential

Troubleshooting GCP Credentials

SSH Key Credentials

Creating an SSH Key Credential

Listing SSH Key Credentials

Using Credentials

With Helm Registries

With GitOps

Managing Credentials

View Credentials

Update a Credential

Delete a Credential

Security

Storage

Best Practices

Troubleshooting

Authentication Errors

Common Issues

API Access