Appliance Release v0.39

Warning

Release v0.39.0 is not yet publicly available.

This page contains the release notes for the v0.39 Anapaya appliance software release. The appliance software release is applicable for the following Anapaya products:

  • Anapaya CORE

  • Anapaya EDGE

  • Anapaya GATE

We recommend always upgrading to the latest available patch release. Please refer to Upgrade Notes (if any) of each release if there are any special steps to be taken when upgrading. For general information on how to upgrade your appliance, please refer to Appliance Update Guide.

v0.39.0 (2024-12-XX)

Features

Appliance Secret Management

This release includes significant changes to the configuration interface due to a redesigned architecture for secret management. The API is designed so that secrets stored on the appliance cannot be releaved either intentionally or accidentally. As a result, configuration and observability data can be exchanged without the risk of exposure.

Starting with this release, secrets are decoupled from configuration. I.e., secrets are referenced in the appliance configuration rather than being included in plain text. Going forward, it will be safe to share the appliance configuration without any post-processing.

Because secrets are referenced in the appliance configuration, they need to be provisioned first. The appliance API is extended with suitable endpoints for secrets management.

Secret Identifier

Secrets are referenced in the configuration via a secret identifier:

  • scheme: <name>@<version>

  • regex with permitted chars: ^[_a-zA-Z0-9:.-]+@[0-9]+$

The initial version must be 1. Subsequent version must be incremented without any gaps. I.e., if the current highest version is x, the next version must be x+1. If you require a more elaborate versioning scheme, we recommend to encode it in the name portion of the secret identifier.

Secrets Management

The Appliance Management API contains three new endpoints to manage secrets:

  • GET /v1/secrets: List the existing secret identifiers.

    Example response

    {
  "secrets": [
    {
      "id": "forwarding-key_1-ff00:0:110@1",
    },
    {
      "id": "loki-password@1",
    }
    {
      "id": "loki-password@2",
    }
  ]
}

  • POST /v1/secrets: Add a new secrets.

    Example request body

    {
  "secret": {
    "id": "bgp-password@1",
    "value": "myBgpPassword"
  }
}

  • POST /v1/secrets/batch: Add a batch of new secrets.

    Example request body

    {
  "secrets": [
    {
      "id": "bgp-password@1",
      "value": "myBgpPassword"
    },
    {
      "id": "forwarding-key_1-ff00:0:110@1",
      "value": "Zm9yd2FyZGtleQo="
    }
  ]
}
Deployment Workflow

So far, the appliance configuration contained plain text secrets directly. With the move to secret references, the appliances needs to be provisioned with secrets first, before they can be referenced in a configuration. This changes the deployment workflow slightly:

  1. Provision the secrets.

  2. Deploy the appliance configuration with secret references.

For example, to add a BGP password for an existing BGP neighbor, you can add the secret using:

# Interactive mode:
$ appliance-cli secrets add bgp-password@1

# Piping the secret from stdin:
$ echo byBgpPassword > secret.txt
$ cat secret.txt | appliance-cli secrets add bgp-password@1

# Using the Management API endpoint
$ echo '{"id": "bgp-password@1", "value": "myBgpPassword"}' > bgp-password.json
$ appliance-cli post secrets secret: @bgp-password.json

Update the appliance configuration to reference the secret:

$ appliance-cli edit config bgp.neighbors[0].auth_password_ref: bgp-password@1

The appliance configuration validation ensures that the referenced secret exists and has the expected format. For some secret references, a specific format of the referenced plain text secret is required. The API documentation of the secret reference field provides information on the expected format if necessary. For example, the forwarding key must be base64 encoded.

Configuration Migration

When upgrading to this release, the existing appliance configuration is automatically migrated. The appliance automatically chooses secret identifiers for the existing secrets in the appliance configuration.

Find the generated secret identifier:

$ appliance-cli get config -f body.config.scion.ases[0].forwarding_key_ref

If you desire a different naming scheme, you can re-provision the secrets with an identifier of your choice and update the references in a configuration update.

Deprecations

Secret References

All fields in the appliance configuration that previously contained secrets have been replaced by fields that now refer to the secrets via the identifier.

The following fields have been changed:

  • old: /bgp/neighbors/{neighbor}/auth_password

    new: /bgp/neighbors/{neighbor}/auth_password_ref

  • old: /management/telemetry/logging/loki/basic_auth/password

    new: /management/telemetry/logging/loki/basic_auth/password_ref

  • old: /management/api/oauth/identity_providers/client_secret

    new: /management/api/oauth/identity_providers/client_secret_ref

  • old: /scion/ases/{as}/forwarding_key

    new: /scion/ases/{as}/forwarding_key_ref

  • old: /scion/ases/{as}/ca_service/anapaya_vault/credentials/secret_id

    new: /scion/ases/{as}/ca_service/anapaya_vault/credentials/secret_id_ref

  • old: /scion/ases/{as}/ca_service/external/shared_secret

    new: /scion/ases/{as}/ca_service/external/shared_secret_ref