diff --git a/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/aws-secrets-manager-dashboard.png b/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/aws-secrets-manager-dashboard.png new file mode 100644 index 00000000000..52f05be3959 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/aws-secrets-manager-dashboard.png differ diff --git a/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/index.md b/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/index.md new file mode 100644 index 00000000000..bf7a898a915 --- /dev/null +++ b/docs/guides/kubernetes/migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine/index.md @@ -0,0 +1,484 @@ +--- +slug: migrate-from-aws-secrets-manager-to-openbao-on-linode-kubernetes-engine +title: "Migrate From AWS Secrets Manager to OpenBao on Akamai Cloud" +description: "Learn how to migrate secrets from AWS Secrets Manager to OpenBao on Linode Kubernetes Engine (LKE) using Helm and AppRole authentication." +authors: ["Akamai"] +contributors: ["Akamai"] +published: 2025-05-01 +keywords: ['aws secrets manager','openbao','migrate secrets from aws','openbao helm install','linode kubernetes engine','eks to openbao','bao kv put','bao approle authentication','open source vault alternative','manage secrets on lke'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[AWS Secrets Manager Documentation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)' +- '[OpenBao Configuration Documentation](https://openbao.org/docs/configuration/)' +- '[OpenBao Integrated Storage](https://openbao.org/docs/concepts/integrated-storage/)' +--- + +AWS Secrets Manager is a fully managed service that securely stores and retrieves sensitive information such as database credentials, API keys, and other application secrets. + +[OpenBao](https://openbao.org/) is an open source fork of [HashiCorp Vault](https://www.vaultproject.io/) that gives teams full control over how secrets are stored, encrypted, and accessed. Unlike managed platforms, OpenBao can be self-hosted in any environment, including on-premises and across multiple clouds. + +This guide walks through how to migrate secrets from AWS Secrets Manager to OpenBao running on Akamai Cloud. + +## Before You Begin + +1. Follow our [Getting Started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) guide to create an Akamai Cloud account if you do not already have one. + +1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. + +1. Install the Linode CLI using the instructions in the [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. + +1. Follow the steps in the *Install `kubectl`* section of the [Getting started with LKE](https://techdocs.akamai.com/cloud-computing/docs/getting-started-with-lke-linode-kubernetes-engine#install-kubectl) guide to install and configure `kubectl`. + +1. Ensure that you have access to your AWS account with sufficient permissions to work with AWS Secrets Manager. The [AWS CLI](https://aws.amazon.com/cli/) and [`eksctl`](https://eksctl.io/) must also be installed and configured. + +1. Install `jq`, a lightweight command line JSON processor. + +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} + +Additionally, this guide contains a number of placeholders that are intended to be replaced by your own unique values. The table below lists these placeholders, what they represent, and the example values used in this guide: + +| Placeholder | Represents | Example Value | +|-------------------------------------------|----------------------------------------------------------|------------------------------------------------| +| `{{< placeholder "AWS_SECRET_NAME" >}}` | The name of the secret in AWS. | `psql` | +| `{{< placeholder "SECRET_MOUNT_PATH" >}}` | The KV mount path used in OpenBao to organize secrets. | `database-credentials` | +| `{{< placeholder "POLICY_FILE" >}}` | The name of the file containing the OpenBao policy. | `db-secrets-policy.hcl` | +| `{{< placeholder "POLICY_NAME" >}}` | The name used to refer to the policy in OpenBao. | `db-secrets-policy` | +| `{{< placeholder "APPROLE_NAME" >}}` | The name used to identify the AppRole in OpenBao. | `web-app-approle` | +| `{{< placeholder "APPROLE_ID" >}}` | The AppRole ID generated by OpenBao. | `1d41b8be-03d2-6f61-702d-1731c957fd13` | +| `{{< placeholder "APPROLE_SECRET_ID" >}}` | The secret ID tied to the AppRole. | `4eb6e604-681c-3fc3-bedd-a2dc774955bb` | +| `{{< placeholder "APPROLE_TOKEN" >}}` | The API token generated using AppRole login. | `s.kpKsgWNtYLAktRYQT4BiMVMy` | +| `{{< placeholder "SECRET_NAME" >}}` | The name of the secret in OpenBao. | `psql` | +| `{{< placeholder "SECRET_KEY_X" >}}` | A key in a structured secret (repeatable). | `username`, `password`, `engine`, `host`, `port`, `dbname` | +| `{{< placeholder "SECRET_VALUE_X" >}}` | The value associated with a `SECRET_KEY_X` (repeatable). | `psqluser`, `W0H@Z52IGI0VjqoGS3xMkJ9SO533w$fcfrmzs.vault-tokenTudDxEe\#`, `postgres`, `psql.example-cloud.com`, `5432`, `web_app_production` | + +{{< note >}} +All of the example values used in this guide are purely examples to mimic the format of actual secrets. These are *not* real credentials to any exisiting systems. +{{< /note >}} + +## Review Existing Secrets in AWS Secrets Manager + +Before migrating to OpenBao, evaluate how your organization currently uses AWS Secrets Manager. + +For example, a web application might rely on database credentials stored in AWS Secrets Manager. Rather than hardcoding these credentials in source code or container images, the application is assigned a role that allows it to retrieve them securely at runtime. This prevents secrets from being exposed through version control or CI/CD pipelines. + +OpenBao supports similar access workflows using dynamic injection, AppRole-based access control, and tight integration with Kubernetes workloads. + +{{< note type="warning" >}} +Ensure that you securely handle any exposed secrets, as they no longer benefit from encryption by AWS Secrets Manager. +{{< /note >}} + +### Review Secrets Using the AWS Console + +In the AWS Secrets Manager dashboard, review your existing secrets. + +![AWS Secrets Manager showing list of stored secrets.](aws-secrets-manager-dashboard.png) + +### Review Secrets Using the AWS CLI + +Alternatively, use the AWS CLI can quickly provide insight into existing secrets and their usage. To list all secrets, run the following command: + +```command +aws secretsmanager list-secrets --query 'SecretList[*].Name' +``` + +```output +[ + "psql-credentials", + "jwt-signing-secret", + "shipping_service_api_key" +] +``` + +To retrieve the secret value for a specific secret, use the {{< placeholder "AWS_SECRET_NAME" >}} (e.g. `jwt-signing-secret`) with the `get-secret-value` command: + +```command +aws secretsmanager get-secret-value \ + --secret-id {{< placeholder "AWS_SECRET_NAME" >}} \ + --query SecretString \ + --output text \ + | jq +``` + +**For Example**: + +```command +aws secretsmanager get-secret-value \ + --secret-id psql-credentials \ + --query SecretString \ + --output text \ + | jq +``` + +```output +{ + "username": "psqluser", + "password": "W0H@Z52IGI0VjqoGS3xMkJ9SO533w$fcfrmzs!m$TudDxEe#", + "engine": "postgres", + "host": "psql.example-cloud.com", + "port": "5432", + "dbname": "web_app_production" +} +``` + +In AWS Secrets Manager, secrets are stored either as key/value pairs or as plaintext. In the previous example, the single `psql-credentials` secret is a set of key/value pairs. + +AWS Secrets Manager uses AWS IAM to control access to secrets. As an example that adopts role-based access control (RBAC), a role such as `DatabaseReader` might have a policy attached that allows the `secretsmanager:GetSecretValue` action on the `psql-credentials` resource. Then, the web application that accesses the database would be given the `DatabaseReader` role so that it can obtain the secret values which would allow it to connect to the database. + +Replicating this setup using OpenBao will involve creating an [application role (AppRole)](https://openbao.org/docs/auth/approle/) to take the place of the AWS IAM role so that applications can use an API token associated with the AppRole to authenticate requests for the secret. + +## Deploy OpenBao on Akamai Cloud + +When migrating from AWS Secrets Manager to OpenBao on Akamai Cloud, your deployment requirements determine whether to install OpenBao on a single Linode Instance or to deploy it in a fault-tolerant environment using the Linode Kubernetes Engine (LKE). Follow the appropriate guide below: + +- [Deploying OpenBao on a Linode Instance](https://docs.google.com/document/d/1x30v1xT_EDuRNnhE9jv5VkFqj9Lo4N3kNO6ICOoSrOM/edit?usp=sharing) +- [Deploying OpenBao on Linode Kubernetes Engine](https://docs.google.com/document/d/1gS6hQg09Ufr1Ku0v528acLESnyj1ZpXTxLhkLIlP-u8/edit?usp=sharing) +- [Deploying OpenBao through the Linode Marketplace](/docs/marketplace-docs/guides/openbao/) + +Regardless of the method used, make sure that: + +- OpenBao is successfully initialized. +- The vault is unsealed. +- The `BAO_ADDR` environment variable is set. +- You are authenticated using the root token. + +### Create a Policy and AppRole + +Use AppRoles to replicate AWS IAM-style access control in OpenBao. In AWS Secrets Manager, applications typically assume IAM roles (e.g. `DatabaseReader`) that permit secret retrieval via policies like `secretsmanager:GetSecretValue`. In OpenBao, equivalent functionality is achieved through policy-bound AppRoles that authorize secrets access through token-based authentication. + +Follow these steps to create an OpenBao AppRole that mimics IAM-based access used in AWS Secrets Manager. + +#### Enable AppRole + +1. [Enable the AppRole authentication method](https://openbao.org/docs/auth/approle/#via-the-api-1): + + ```command + bao auth enable approle + ``` + + ```output + Success! Enabled approle auth method at: approle/ + ``` + +#### Create a Policy + +2. Create a new `.hcl` [policy file](https://openbao.org/docs/concepts/policies/) in `/etc/openbao`, replacing {{< placeholder "POLICY_FILE" >}} (e.g. `db-secrets-policy.hcl`) with a policy filename of your choosing: + + ```command + sudo nano /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example:** + + ```command + sudo nano /etc/openbao/db-secrets-policy.hcl + ``` + +1. Give the file the following contents, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} (e.g. `database-credentials`) with your chosen mount path: + + ```file {title="POLICY_FILE.hcl"} + path "{{< placeholder "SECRET_MOUNT_PATH" >}}/*" { + capabilities = ["read"] + } + ``` + + **For Example**: + + ```file {title="db-secrets-policy.hcl"} + path "database-credentials/*" { + capabilities = ["read"] + } + ``` + + This policy grants read access to any secrets within the specified mount path. + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Add the policy to OpenBao, replacing {{< placeholder "POLICY_NAME" >}} (e.g. `db-secrets-policy`) and {{< placeholder "POLICY_FILE" >}}: + + ```command + bao policy write {{< placeholder "POLICY_NAME" >}} /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + bao policy write db-secrets-policy /etc/openbao/db-secrets-policy.hcl + ``` + + ```output + Success! Uploaded policy: db-secrets-policy + ``` + +#### Create an AppRole + +5. Create an AppRole for the application that needs access to the secret, replacing {{< placeholder "APPROLE_NAME" >}} (e.g. `web-app-approle`) and {{< placeholder "POLICY_NAME" >}}: + + ```command + bao write auth/approle/role/{{< placeholder "APPROLE_NAME" >}} token_policies={{< placeholder "POLICY_NAME" >}} + ``` + + **For Example**: + + ```command + bao write auth/approle/role/web-app-approle token_policies=db-secrets-policy + ``` + + ```output + Success! Data written to: auth/approle/role/web-app-approle + ``` + +1. Verify that the AppRole was written successfully, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}} + ``` + + **For Example**: + + ```command + bao read auth/approle/role/web-app-approle + ``` + + ```output + Key Value + --- ----- + bind_secret_id true + local_secret_ids false + secret_id_bound_cidrs + secret_id_num_uses 0 + secret_id_ttl 0s + token_bound_cidrs [] + token_explicit_max_ttl 0s + token_max_ttl 0s + token_no_default_policy false + token_num_uses 0 + token_period 0s + token_policies [db-secrets-policy] + token_strictly_bind_ip false + token_ttl 0s + token_type default + ``` + +1. Fetch the AppRole ID, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/role-id + ``` + + **For Example**: + + ```command + bao read auth/approle/role/web-app-approle/role-id + ``` + + ```output + Key Value + --- ----- + role_id 1d41b8be-03d2-6f61-702d-1731c957fd13 + ``` + +#### Generate a Secret ID + +8. Generate a secret ID for the role, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao write -f auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/secret-id + ``` + + **For Example**: + + ```command + bao write -f auth/approle/role/web-app-approle/secret-id + ``` + + ```output + Key Value + --- ----- + secret_id 4eb6e604-681c-3fc3-bedd-a2dc774955bb + secret_id_accessor fe899dc6-85f7-f596-fb93-3c961f7919a9 + secret_id_num_uses 0 + secret_id_ttl 0s + ``` + +#### Generate an API Token + +9. Generate an API token for the AppRole, supplying the {{< placeholder "APPROLE_ID" >}} (e.g. `1d41b8be-03d2-6f61-702d-1731c957fd13`) and the {{< placeholder "APPROLE_SECRET_ID" >}} (e.g. `4eb6e604-681c-3fc3-bedd-a2dc774955bb`) from the previous commands: + + ```command + bao write auth/approle/login \ + role_id="{{< placeholder "APPROLE_ID" >}}" \ + secret_id="{{< placeholder "APPROLE_SECRET_ID" >}}" + ``` + + **For Example**: + + ```command + bao write auth/approle/login \ + role_id="1d41b8be-03d2-6f61-702d-1731c957fd13" \ + secret_id="4eb6e604-681c-3fc3-bedd-a2dc774955bb" + ``` + + ```output + Key Value + --- ----- + token s.kpKsgWNtYLAktRYQT4BiMVMy + token_accessor Rwlq5EmvrHC8VvvHwoRyJzUh + token_duration 768h + token_renewable true + token_policies ["db-secrets-policy" "default"] + identity_policies [] + policies ["db-secrets-policy" "default"] + token_meta_role_name web-app-approle + ``` + + The resulting AppRole token (e.g. `s.kpKsgWNtYLAktRYQT4BiMVMy`) can be used by a user, machine, or service, such a web application, to authenticate OpenBao API calls, giving the caller authorization to read the database credential secret. + +### Storing Secrets + +Create the secret store defined in the policy created above. + +1. Enable the KV secrets engine, replacing {{< placeholder "SECRET_MOUNT_PATH" >}}: + + ```command + bao secrets enable --path={{< placeholder "SECRET_MOUNT_PATH" >}} kv + ``` + + **For Example**: + + ```command + bao secrets enable --path=database-credentials kv + ``` + + ```output + Success! Enabled the kv secrets engine at: database-credentials/ + ``` + +1. The example database secret stored at AWS Secrets Manager includes multiple fields stored as a JSON object. Store a structured secret such as this in the {{< placeholder "SECRET_MOUNT_PATH" >}} as a secret named {{< placeholder "SECRET_NAME" >}} (e.g. `psql`): + + ```command + bao kv put --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} \ + "{{< placeholder "SECRET_KEY_1" >}}"="{{< placeholder "SECRET_VALUE_1" >}}" \ + "{{< placeholder "SECRET_KEY_2" >}}"="{{< placeholder "SECRET_VALUE_2" >}}" \ + "{{< placeholder "SECRET_KEY_3" >}}"="{{< placeholder "SECRET_VALUE_3" >}}" \ + "{{< placeholder "SECRET_KEY_4" >}}"="{{< placeholder "SECRET_VALUE_4" >}}" \ + "{{< placeholder "SECRET_KEY_5" >}}"="{{< placeholder "SECRET_VALUE_5" >}}" \ + "{{< placeholder "SECRET_KEY_6" >}}"="{{< placeholder "SECRET_VALUE_6" >}}" + ``` + + **For Example**: + + ```command + bao kv put --mount=database-credentials psql \ + "username"="psqluser" \ + "password"="W0H@Z52IGI0VjqoGS3xMkJ9SO533w$fcfrmzs.vault-tokenTudDxEe\#" \ + "engine"="postgres" \ + "host"="psql.example-cloud.com" \ + "port"="5432" \ + "dbname"="web_app_production" + ``` + + ```output + Success! Data written to: database-credentials/psql + ``` + +### Retrieving Secrets + +1. While authenticated with the root token, retrieve the secret using the OpenBao CLI, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} and {{< placeholder "SECRET_NAME" >}}: + + ```command + bao kv get --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} + ``` + + **For Example**: + + ```command + bao kv get --mount=database-credentials psql + ``` + + ```output + ====== Data ====== + Key Value + --- ----- + dbname web_app_production + engine postgres + host psql.example-cloud.com + password W0H@Z52IGI0VjqoGS3xMkJ9SO533w.vault-tokenTudDxEe\# + port 5432 + username psqluser + ``` + +1. Test access using the {{< placeholder "APPROLE_TOKEN" >}} saved earlier (e.g. `s.36Yb3ijEOJbifprhdEiFtPhR`), your {{< placeholder "SECRET_MOUNT_PATH" >}}, and the {{< placeholder "SECRET_NAME" >}}: + + ```command + curl --header "X-Vault-Token: {{< placeholder "APPROLE_TOKEN" >}}" \ + --request GET \ + $BAO_ADDR/v1/{{< placeholder "SECRET_MOUNT_PATH" >}}/{{< placeholder "SECRET_NAME" >}} \ + | jq + ``` + + **For Example**: + + ```command + curl --header "X-Vault-Token: s.36Yb3ijEOJbifprhdEiFtPhR" \ + --request GET \ + $BAO_ADDR/v1/database-credentials/psql \ + | jq + ``` + + ```output + { + "request_id": "00237a0b-4349-351d-50a0-ef127534ed18", + "lease_id": "", + "renewable": false, + "lease_duration": 2764800, + "data": { + "dbname": "web_app_production", + "engine": "postgres", + "host": "psql.example-cloud.com", + "password": "W0H@Z52IGI0VjqoGS3xMkJ9SO533w.vault-tokenTudDxEe#", + "port": "5432", + "username": "psqluser" + }, + "wrap_info": null, + "warnings": null, + "auth": null + } + ``` + + The AppRole token can be used by applications or services to retrieve secrets through the OpenBao API. + + {{< note >}} + According to the [OpenBao API documentation](https://openbao.org/api-docs/libraries/), OpenBao is API-compatible with HashiCorp Vault. This means most Vault client libraries should also work with OpenBao, including: + + - [Go](https://github.com/hashicorp/vault/tree/main/api) + - [Ruby](https://github.com/hashicorp/vault-ruby) + - [C#](https://github.com/rajanadar/VaultSharp) + - [Java](https://developer.hashicorp.com/vault/api-docs/libraries#java) + - [Kotlin](https://github.com/kunickiaj/vault-kotlin) + - [Node.js](https://developer.hashicorp.com/vault/api-docs/libraries#node-js) + - [PHP](https://developer.hashicorp.com/vault/api-docs/libraries#php) + - [Python](https://github.com/hvac/hvac) + {{< /note >}} + +## Production Considerations + +When migrating from AWS Secrets Manager to OpenBao on Akamai Cloud, it's important to ensure your deployment is secure, resilient, and optimized for performance. This section covers key security and high availability considerations to help you maintain a reliable and protected secrets management system. + +### Security + +For a production-grade OpenBao deployment, security should be a top priority. Protecting secrets from unauthorized access, ensuring secure communication, and enforcing strict access controls are essential to maintaining a secure environment. + +- **Access Control Policies**: Use OpenBao's [policy](https://openbao.org/docs/concepts/policies/) system to enforce RBAC. Define granular policies that grant only the necessary permissions, following the principle of least privilege. +- **Audit Logging**: Enable [detailed audit logs](https://openbao.org/docs/configuration/log-requests-level/) to track all access and modifications to secrets. OpenBao supports multiple logging backends, such as syslog and file-based logs, to help monitor suspicious activity. +- **Secrets Lifecycle Management**: Implement automated secrets rotation, revocation, and expiration to ensure secrets do not become stale or overexposed. Consider using dynamic secrets where possible to generate time-limited credentials. +- **Securing Network Communication**: Configure OpenBao to [use TLS to encrypt](https://openbao.org/docs/configuration/listener/tcp/#configuring-tls) all communications, ensuring data in transit remains secure. Regularly rotate TLS certificates to prevent expiration-related outages and reduce the risk of compromised certificates. + +### High Availability + +For production environments, OpenBao should be deployed with fault tolerance and scalability in mind. OpenBao’s [Autopilot mode](https://openbao.org/docs/concepts/integrated-storage/autopilot) for [high availability](https://openbao.org/docs/internals/high-availability/) ensures that if the active node fails, the cluster automatically elects a new leader, maintaining uptime without manual intervention. However, to enable seamless failover, organizations must configure their deployment correctly, and proactively monitor system health. + +- **Raft Storage Backend**: Use OpenBao’s [integrated storage](https://openbao.org/docs/internals/integrated-storage/), based on the [Raft protocol](https://thesecretlivesofdata.com/raft/), to enable distributed data replication across multiple nodes. This ensures data consistency and fault tolerance while reducing reliance on external storage backends. Configure regular Raft snapshots for disaster recovery. +- **Deploy Multiple Nodes**: OpenBao recommends at least five nodes for a [high-availability deployment](https://openbao.org/docs/concepts/ha/). The active node handles all requests, while standby nodes remain ready to take over in case of failure. +- **Monitor Leader Status**: Use [bao operator raft list-peers](https://openbao.org/docs/commands/operator/raft/#list-peers) to check the cluster’s leader and node statuses. This command helps ensure that standby nodes are correctly registered and ready for failover. \ No newline at end of file diff --git a/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-access-control.png b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-access-control.png new file mode 100644 index 00000000000..91aaa029331 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-access-control.png differ diff --git a/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-list.png b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-list.png new file mode 100644 index 00000000000..f17bee886ab Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-list.png differ diff --git a/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-value.png b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-value.png new file mode 100644 index 00000000000..2b36bb47cae Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/azure-key-vault-secret-value.png differ diff --git a/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/index.md b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/index.md new file mode 100644 index 00000000000..a8092328494 --- /dev/null +++ b/docs/guides/kubernetes/migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine/index.md @@ -0,0 +1,477 @@ +--- +slug: migrate-from-azure-key-vault-to-openbao-on-linode-kubernetes-engine +title: "Migrate From Azure Key Vault to OpenBao on Akamai Cloud" +description: "Migrate secrets from Azure Key Vault to OpenBao on Linode Kubernetes Engine (LKE) with Helm and RBAC for secure secret management." +authors: ["Akamai"] +contributors: ["Akamai"] +published: 2025-05-01 +keywords: ['azure key vault','openbao','migrate secrets from azure','openbao helm install','linode kubernetes engine','aks to openbao','bao kv put','bao approle authentication','open source vault alternative','manage secrets on lke'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Azure Key Vault Documentation](https://learn.microsoft.com/en-us/azure/key-vault/)' +- '[Azure `az` CLI Documentation](https://learn.microsoft.com/en-us/cli/azure/)' +- '[OpenBao Configuration Documentation](https://openbao.org/docs/configuration/)' +- '[OpenBao Integrated Storage](https://openbao.org/docs/concepts/integrated-storage/)' +--- + +Azure Key Vault is a managed cloud service that secures secrets, keys, and certificates for application security and compliance in Microsoft Azure. It provides centralized control and access policies so that developers and security teams can safeguard sensitive information such as API keys or passwords. + +[OpenBao](https://openbao.org/) is an open source fork of [HashiCorp Vault](https://www.vaultproject.io/) that gives teams full control over how secrets are stored, encrypted, and accessed. Unlike managed platforms, OpenBao can be self-hosted in any environment, including on-premises and across multiple clouds. + +This guide walks through how to migrate secrets stored in Azure Key Vault to OpenBao running on Akamai Cloud. + +## Before You Begin + +1. Follow our [Getting Started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) guide to create an Akamai Cloud account if you do not already have one. + +1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. + +1. Install the Linode CLI using the instructions in the [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. + +1. Follow the steps in the *Install `kubectl`* section of the [Getting started with LKE](https://techdocs.akamai.com/cloud-computing/docs/getting-started-with-lke-linode-kubernetes-engine#install-kubectl) guide to install and configure `kubectl`. + +1. Ensure that you have access to your Azure account with sufficient permissions to work with Azure Key Vault. The [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) must also be installed and configured. + +1. Install `jq`, a lightweight command line JSON processor. + +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} + +Additionally, this guide contains a number of placeholders that are intended to be replaced by your own unique values. The table below lists these placeholders, what they represent, and the example values used in this guide: + +| Placeholder | Represents | Example Value | +|-------------------------------------------|-------------------------------------------------------|----------------------------------------| +| `{{< placeholder "AZURE_VAULT_NAME" >}}` | The name of the Azure Key Vault | `my-app-vault` | +| `{{< placeholder "AZURE_SECRET_NAME" >}}` | Name of a secret stored in Azure Key Vault | `LLM-service-key` | +| `{{< placeholder "POLICY_FILE" >}}` | Filename of the `.hcl` policy definition | `api-keys-secrets-policy.hcl` | +| `{{< placeholder "SECRET_MOUNT_PATH" >}}` | Mount path in OpenBao KV store for organizing secrets | `api-keys` | +| `{{< placeholder "POLICY_NAME" >}}` | Name of the OpenBao policy | `api-keys-secrets-policy` | +| `{{< placeholder "APPROLE_NAME" >}}` | Name of the OpenBao AppRole | `api-key-reader-approle` | +| `{{< placeholder "APPROLE_ID" >}}` | AppRole ID for authenticating in OpenBao | `e633701e-893e-460d-8012-ea2afedbcd87` | +| `{{< placeholder "APPROLE_SECRET_ID" >}}` | Secret ID associated with the AppRole | `725d9076-5a5c-4921-98f7-7535c767386a` | +| `{{< placeholder "APPROLE_TOKEN" >}}` | API token retrieved from OpenBao using the AppRole | `s.36Yb3ijEOJbifprhdEiFtPhR` | +| `{{< placeholder "SECRET_NAME" >}}` | Name of the secret to store in OpenBao | `llm-service` | +| `{{< placeholder "SECRET_VALUE" >}}` | Value of the secret to store in OpenBao | `0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&...` | + +{{< note >}} +All of the example values used in this guide are purely examples to mimic the format of actual secrets. These are *not* real credentials to any exisiting systems. +{{< /note >}} + +## Review Existing Secrets in Azure Key Vault + +Before migrating to OpenBao, evaluate how your organization currently uses Azure Key Vault. + +For example, an application that uses third-party services, such as an LLM platform or a digital payment processor, might retrieve API keys at runtime using a role assignment. This ensures the keys aren't hardcoded into application images or checked into source control. + +OpenBao offers similar capabilities using role-based access, dynamic injection, and integration with Kubernetes. + +{{< note type="warning" >}} +Ensure that you securely handle any exposed secrets, as they no longer benefit from encryption by Azure Key Vault. +{{< /note >}} + +### Review Secrets Using the Azure Portal + +1. Navigate to your key vault and open the **Secrets** tab: + + ![Azure Key Vault UI showing list of secrets.](azure-key-vault-secret-list.png) + +1. Select a secret, choose the latest version, then click **Show Secret Value**: + + ![Azure Key Vault UI showing how to view the value of a selected secret.](azure-key-vault-secret-value.png) + +{{< note >}} +Azure uses IAM with role based access control (RBAC) to manage which users and services can access secrets. + +For example, an Azure VM within your Resource Group might need access to the LLM service API key stored within your vault. The VM would be assigned the [`Key Vault Secrets User role`](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli#azure-built-in-roles-for-key-vault-data-plane-operations), allowing it to read the contents of secrets in the vault. + +To view role assignments in the Azure portal, navigate to your key vault, select **Access control (IAM)**, then open the **Role assignments** tab: + +![Azure Key Vault Access control IAM role assignments tab.](azure-key-vault-access-control.png) +{{< /note >}} + +### Review Secrets Using the Azure CLI + +You can also use the Azure CLI (`az`) to manage the secrets in your key vault. + +1. [List all the secrets in your vault](https://learn.microsoft.com/en-us/cli/azure/keyvault/secret?view=azure-cli-latest#az-keyvault-secret-list) by specifying the {{< placeholder "AZURE_VAULT_NAME" >}} (e.g. `my-app-vault`): + + ```command + az keyvault secret list \ + --vault-name "{{< placeholder "AZURE_VAULT_NAME" >}}" \ + --query "\[\].name" + ``` + + **For Example**: + + ```command + az keyvault secret list \ + --vault-name "my-app-vault" \ + --query "\[\].name" + ``` + + ```output + [ + "github-deploy-key", + "LLM-service-key", + "payments-service-dev-key", + "telemetry-export-api-key" + ] + ``` + +1. Retrieve the [value of a single secret](https://learn.microsoft.com/en-us/cli/azure/keyvault/secret?view=azure-cli-latest#az-keyvault-secret-show) by providing both the {{< placeholder "AZURE_VAULT_NAME" >}} and {{< placeholder "AZURE_SECRET_NAME" >}} (e.g. `LLM-service-key`). + + ```command + az keyvault secret show \ + --vault-name "{{< placeholder "AZURE_VAULT_NAME" >}}" \ + --name "{{< placeholder "AZURE_SECRET_NAME" >}}" \ + --query "value" + ``` + + **For Example**: + + ```command + az keyvault secret show \ + --vault-name "my-app-vault" \ + --name "LLM-service-key" \ + --query "value" + ``` + + ```output + "0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&RSa47jljP4nMVs7qG#n87Lai46niZUCrLP" + ``` + +## Deploy OpenBao on Akamai Cloud + +When migrating from Azure Key Vault to OpenBao on Akamai Cloud, your deployment requirements determine whether to install OpenBao on a single Linode Instance or to deploy it in a fault-tolerant environment using the Linode Kubernetes Engine (LKE). Follow the appropriate guide below: + +- [Deploying OpenBao on a Linode Instance](https://docs.google.com/document/d/1x30v1xT_EDuRNnhE9jv5VkFqj9Lo4N3kNO6ICOoSrOM/edit?usp=sharing) +- [Deploying OpenBao on Linode Kubernetes Engine](https://docs.google.com/document/d/1gS6hQg09Ufr1Ku0v528acLESnyj1ZpXTxLhkLIlP-u8/edit?usp=sharing) +- [Deploying OpenBao through the Linode Marketplace](/docs/marketplace-docs/guides/openbao/) + +Regardless of the method used, make sure that: + +- OpenBao is successfully initialized. +- The vault is unsealed. +- The `BAO_ADDR` environment variable is set. +- You are authenticated using the root token. + +### Create a Policy and AppRole + +Use AppRoles to replicate Azure’s IAM-based access control in OpenBao. In Azure Key Vault, access is granted to users or services through role assignments, such as the *Key Vault Secrets User* role. In OpenBao, equivalent functionality is implemented using policies attached to AppRoles. + +Follow these steps to create an OpenBao AppRole that mirrors the access control model used in Azure IAM. + +#### Enable AppRole + +1. Enable the AppRole authentication method: + + ```command + bao auth enable approle + ``` + + ```output + Success! Enabled approle auth method at: approle/ + ``` + +#### Create a Policy + +2. Create a new `.hcl` [policy file](https://openbao.org/docs/concepts/policies/) in `/etc/openbao`, replacing {{< placeholder "POLICY_FILE" >}} (e.g. `api-keys-secrets-policy.hcl`) with a policy filename of your choosing: + + ```command + sudo nano /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + sudo nano /etc/openbao/api-keys-secrets-policy.hcl + ``` + +1. Give the file the following contents, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} (e.g. `api-keys`) with your chosen mount path: + + ```file {title="POLICY_FILE.hcl"} + path "{{< placeholder "SECRET_MOUNT_PATH" >}}/*" { + capabilities = ["read"] + } + ``` + + **For Example**: + + ```file {title="api-keys-secrets-policy.hcl"} + path "api-keys/*" { + capabilities = ["read"] + } + ``` + + This policy grants read access to any secrets within the specified mount path. + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Add the policy to OpenBao, replacing {{< placeholder "POLICY_NAME" >}} (e.g. `api-keys-secrets-policy`) and {{< placeholder "POLICY_FILE" >}}: + + ```command + bao policy write {{< placeholder "POLICY_NAME" >}} /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + bao policy write api-keys-secrets-policy /etc/openbao/api-keys-secrets-policy.hcl + ``` + + ```output + Success! Uploaded policy: api-keys-secrets-policy + ``` + +#### Create an AppRole + +5. Create an AppRole for the application that needs access to the secret, replacing {{< placeholder "APPROLE_NAME" >}} (e.g. `api-key-reader-approle`) and {{< placeholder "POLICY_NAME" >}}: + + ```command + bao write auth/approle/role/{{< placeholder "APPROLE_NAME" >}} token_policies={{< placeholder "POLICY_NAME" >}} + ``` + + **For Example**: + + ```command + bao write auth/approle/role/api-key-reader-approle token_policies=api-keys-secrets-policy + ``` + + ```output + Success! Data written to: auth/approle/role/api-key-reader-approle + ``` + +1. Verify that the AppRole was written successfully, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}} + ``` + + **For Example**: + + ```command + bao read auth/approle/role/api-key-reader-approle + ``` + + ```output + Key Value + --- ----- + bind_secret_id true + local_secret_ids false + secret_id_bound_cidrs + secret_id_num_uses 0 + secret_id_ttl 0s + token_bound_cidrs [] + token_explicit_max_ttl 0s + token_max_ttl 0s + token_no_default_policy false + token_num_uses 0 + token_period 0s + token_policies [api-keys-secrets-policy] + token_strictly_bind_ip false + token_ttl 0s + token_type default + ``` + +1. Fetch the AppRole ID, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/role-id + ``` + + **For Example**: + + ```command + bao read auth/approle/role/api-key-reader-approle/role-id + ``` + + ```output + Key Value + --- ----- + role_id e633701e-893e-460d-8012-ea2afedbcd87 + ``` + +#### Generate a Secret ID + +8. Generate a secret ID for the role, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao write -f auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/secret-id + ``` + + **For Example**: + + ```command + bao write -f auth/approle/role/api-key-reader-approle/secret-id + ``` + + ```output + Key Value + --- ----- + secret_id 725d9076-5a5c-4921-98f7-7535c767386a + secret_id_accessor b780e4d6-a2f2-4e03-8843-3e6a88b56f09 + secret_id_num_uses 0 + secret_id_ttl 0s + ``` + +#### Generate an API Token + +9. Generate an API token for the AppRole, supplying the {{< placeholder "APPROLE_ID" >}} (e.g. `e633701e-893e-460d-8012-ea2afedbcd87`) and the {{< placeholder "APPROLE_SECRET_ID" >}} (e.g. `725d9076-5a5c-4921-98f7-7535c767386a`) from the previous commands: + + ```command + bao write auth/approle/login \ + role_id=" {{< placeholder "APPROLE_ID" >}}" \ + secret_id="{{< placeholder "APPROLE_SECRET_ID" >}}" + ``` + + **For Example**: + + ```command + bao write auth/approle/login \ + role_id=" e633701e-893e-460d-8012-ea2afedbcd87" \ + secret_id="725d9076-5a5c-4921-98f7-7535c767386a" + ``` + + ```output + Key Value + --- ----- + token s.TuQBY39kkpEDOqKcKYbWvpmZ + token_accessor N1qSJiqOz6mXlpbmFVT2LOfS + token_duration 768h + token_renewable true + token_policies ["api-keys-secrets-policy" "default"] + identity_policies [] + policies ["api-keys-secrets-policy" "default"] + token_meta_role_name api-key-reader-approle + ``` + + The resulting AppRole token (e.g. `s.TuQBY39kkpEDOqKcKYbWvpmZ`) can be used by a user, machine, or service, such a web application, to authenticate OpenBao API calls, giving the caller authorization to read the LLM service API key secret. + +### Storing Secrets + +Create the secret store defined in the policy created above. + +1. Enable the KV secrets engine, replacing {{< placeholder "SECRET_MOUNT_PATH" >}}: + + ```command + bao secrets enable --path={{< placeholder "SECRET_MOUNT_PATH" >}} kv + ``` + + **For Example**: + + ```command + bao secrets enable --path=api-keys kv + ``` + + ```output + Success! Enabled the kv secrets engine at: api-keys/ + ``` + +1. Store your {{< placeholder "SECRET_VALUE" >}} (e.g. `0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&RSa47jljP4nMVs7qG#n87Lai46niZUCrLP`) in the {{< placeholder "SECRET_MOUNT_PATH" >}} as a secret named {{< placeholder "SECRET_NAME" >}} (e.g. `llm-service`): + + ```command + bao kv put --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} \ + "key"="{{< placeholder "SECRET_VALUE" >}}" + ``` + + **For Example**: + + ```command + bao kv put --mount=api-keys llm-service \ + "key"="0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&RSa47jljP4nMVs7qG#n87Lai46niZUCrLP" + ``` + + ```output + Success! Data written to: api-keys/llm-service + ``` + +### Retrieving Secrets + +1. While authenticated with the root token, retrieve the secret using the OpenBao CLI, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} and {{< placeholder "SECRET_NAME" >}}: + + ```command + bao kv get --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} + ``` + + **For Example**: + + ```command + bao kv get --mount=api-keys llm-service + ``` + + ```output + ====== Data ====== + Key Value + --- ----- + key 0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&RSa47jljP4nMVs7qG#n87Lai46niZUCrLP + ``` + +1. Test access using the {{< placeholder "APPROLE_TOKEN" >}} (e.g. `s.36Yb3ijEOJbifprhdEiFtPhR`) saved earlier, your {{< placeholder "SECRET_MOUNT_PATH" >}}, and the {{< placeholder "SECRET_NAME" >}}: + + ```command + curl --header "X-Vault-Token: {{< placeholder "APPROLE_TOKEN" >}}" \ + --request GET \ + $BAO_ADDR/v1/{{< placeholder "SECRET_MOUNT_PATH" >}}/{{< placeholder "SECRET_NAME" >}} \ + | jq + ``` + + **For Example**: + + ```command + curl --header "X-Vault-Token: s.36Yb3ijEOJbifprhdEiFtPhR" \ + --request GET \ + $BAO_ADDR/v1/api-keys/llm-service \ + | jq + ``` + + ```output + { + "request_id": "4ea9a66e-c63a-433c-b2e2-015c39c45086", + "lease_id": "", + "renewable": false, + "lease_duration": 2764800, + "data": { + "key": "0z7NUSJ6gHKoWLkO5q2%Zq1E1do%m&RSa47jljP4nMVs7qG#n87Lai46niZUCrLP" + }, + "wrap_info": null, + "warnings": null, + "auth": null + } + ``` + + The AppRole token can be used by applications or services to retrieve secrets through the OpenBao API. + + {{< note >}} + According to the [OpenBao API documentation](https://openbao.org/api-docs/libraries/), OpenBao is API-compatible with HashiCorp Vault. This means most Vault client libraries should also work with OpenBao, including: + + - [Go](https://github.com/hashicorp/vault/tree/main/api) + - [Ruby](https://github.com/hashicorp/vault-ruby) + - [C#](https://github.com/rajanadar/VaultSharp) + - [Java](https://developer.hashicorp.com/vault/api-docs/libraries#java) + - [Kotlin](https://github.com/kunickiaj/vault-kotlin) + - [Node.js](https://developer.hashicorp.com/vault/api-docs/libraries#node-js) + - [PHP](https://developer.hashicorp.com/vault/api-docs/libraries#php) + - [Python](https://github.com/hvac/hvac) + {{< /note >}} + +## Production Considerations + +When migrating from Azure Key Vault to OpenBao on Akamai Cloud, it's important to ensure your deployment is secure, resilient, and optimized for performance. This section covers key security and high availability considerations to help you maintain a reliable and protected secrets management system. + +### Security + +For a production-grade OpenBao deployment, security should be a top priority. Protecting secrets from unauthorized access, ensuring secure communication, and enforcing strict access controls are essential to maintaining a secure environment. + +- **Access Control Policies**: Use OpenBao's [policy](https://openbao.org/docs/concepts/policies/) system to enforce RBAC. Define granular policies that grant only the necessary permissions, following the principle of least privilege. +- **Audit Logging**: Enable [detailed audit logs](https://openbao.org/docs/configuration/log-requests-level/) to track all access and modifications to secrets. OpenBao supports multiple logging backends, such as syslog and file-based logs, to help monitor suspicious activity. +- **Secrets Lifecycle Management**: Implement automated secrets rotation, revocation, and expiration to ensure secrets do not become stale or overexposed. Consider using dynamic secrets where possible to generate time-limited credentials. +- **Securing Network Communication**: Configure OpenBao to [use TLS to encrypt](https://openbao.org/docs/configuration/listener/tcp/#configuring-tls) all communications, ensuring data in transit remains secure. Regularly rotate TLS certificates to prevent expiration-related outages and reduce the risk of compromised certificates. + +### High Availability + +For production environments, OpenBao should be deployed with fault tolerance and scalability in mind. OpenBao’s [Autopilot mode](https://openbao.org/docs/concepts/integrated-storage/autopilot) for [high availability](https://openbao.org/docs/internals/high-availability/) ensures that if the active node fails, the cluster automatically elects a new leader, maintaining uptime without manual intervention. However, to enable seamless failover, organizations must configure their deployment correctly, and proactively monitor system health. + +- **Raft Storage Backend**: Use OpenBao’s [integrated storage](https://openbao.org/docs/internals/integrated-storage/), based on the [Raft protocol](https://thesecretlivesofdata.com/raft/), to enable distributed data replication across multiple nodes. This ensures data consistency and fault tolerance while reducing reliance on external storage backends. Configure regular Raft snapshots for disaster recovery. +- **Deploy Multiple Nodes**: OpenBao recommends at least five nodes for a [high-availability deployment](https://openbao.org/docs/concepts/ha/). The active node handles all requests, while standby nodes remain ready to take over in case of failure. +- **Monitor Leader Status**: Use [bao operator raft list-peers](https://openbao.org/docs/commands/operator/raft/#list-peers) to check the cluster’s leader and node statuses. This command helps ensure that standby nodes are correctly registered and ready for failover. \ No newline at end of file diff --git a/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-list.png b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-list.png new file mode 100644 index 00000000000..fa738d0bf18 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-list.png differ diff --git a/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-value.png b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-value.png new file mode 100644 index 00000000000..a94d11ab742 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/gcp-secret-manager-secret-value.png differ diff --git a/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/index.md b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/index.md new file mode 100644 index 00000000000..b0b76f578cb --- /dev/null +++ b/docs/guides/kubernetes/migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine/index.md @@ -0,0 +1,469 @@ +--- +slug: migrate-from-gcp-secret-manager-to-openbao-on-linode-kubernetes-engine +title: "Migrate From GCP Secret Manager to OpenBao on Akamai Cloud" +description: "Migrate secrets from GCP Secret Manager to OpenBao on Linode Kubernetes Engine (LKE) using Helm charts and role-based access policies." +authors: ["Akamai"] +contributors: ["Akamai"] +published: 2025-05-01 +keywords: ['gcp secret manager','openbao','migrate secrets from gcp','openbao helm install','linode kubernetes engine','gke to openbao','bao kv put','bao approle authentication','open source vault alternative','manage secrets on lke'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Google Cloud Secret Manager Documentation](https://cloud.google.com/secret-manager/docs)' +- '[gcloud secrets documentation](https://cloud.google.com/sdk/gcloud/reference/secrets)' +- '[OpenBao Configuration Documentation](https://openbao.org/docs/configuration/)' +- '[OpenBao Integrated Storage](https://openbao.org/docs/concepts/integrated-storage/)' +--- + +Google Cloud Platform (GCP) Secret Manager is a managed service that securely stores sensitive data like API keys, passwords, and certificates. It integrates with other GCP services and simplifies access control through Identity and Access Management (IAM). + +[OpenBao](https://openbao.org/) is an open source fork of [HashiCorp Vault](https://www.vaultproject.io/) that gives teams full control over how secrets are stored, encrypted, and accessed. Unlike managed platforms, OpenBao can be self-hosted in any environment, including on-premises and across multiple clouds. + +This guide walks through how to migrate secrets from GCP Secret Manager to OpenBao running on Akamai Cloud. + +## Before You Begin + +1. Follow our [Getting Started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) guide to create an Akamai Cloud account if you do not already have one. + +1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. + +1. Install the Linode CLI using the instructions in the [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. + +1. Follow the steps in the *Install `kubectl`* section of the [Getting started with LKE](https://techdocs.akamai.com/cloud-computing/docs/getting-started-with-lke-linode-kubernetes-engine#install-kubectl) guide to install and configure `kubectl`. + +1. Ensure that you have access to your GCP account with sufficient permissions to work with GCP Secret Manager. The [gcloud CLI](https://cloud.google.com/sdk/docs/install) must also be installed and configured. + +1. Install `jq`, a lightweight command line JSON processor. + +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} + +Additionally, this guide contains a number of placeholders that are intended to be replaced by your own unique values. The table below lists these placeholders, what they represent, and the example values used in this guide: + +| Placeholder | Represents | Example Value | +|-----------------------------------------|------------------------------------------------------------|----------------------------------------| +| {{< placeholder "GCP_PROJECT_ID" >}} | Google Cloud project ID. | `ecommerce-application-454116` | +| {{< placeholder "GCP_SECRET_NAME" >}} | Name of a secret stored in GCP Secret Manager. | `jwt-signing-secret` | +| {{< placeholder "POLICY_FILE" >}} | Name of the local file where the OpenBao policy is stored. | `jwt-secrets-policy.hcl` | +| {{< placeholder "SECRET_MOUNT_PATH" >}} | Mount path for KV engine in OpenBao. | `jwt` | +| {{< placeholder "POLICY_NAME" >}} | OpenBao policy name. | `jwt-secrets-policy` | +| {{< placeholder "APPROLE_NAME" >}} | Name of the AppRole in OpenBao. | `app-authenticator-approle` | +| {{< placeholder "APPROLE_ID" >}} | ID of the AppRole generated by OpenBao. | `019e2cc5-b8ce-4aa4-91b9-c2c9e9e59863` | +| {{< placeholder "APPROLE_SECRET_ID" >}} | Secret ID created for the AppRole. | `cef786fb-1d1c-4c52-9466-aea47b3c8d3a` | +| {{< placeholder "SECRET_VALUE" >}} | The actual secret value to be stored in OpenBao. | `EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW` | +| {{< placeholder "SECRET_NAME" >}} | The name of the secret in OpenBao. | `signer` | +| {{< placeholder "APPROLE_TOKEN" >}} | Token generated from AppRole login. | `s.dy572yUtTNvHTZgIoxdNVO41` | + +{{< note >}} +All of the example values used in this guide are purely examples to mimic the format of actual secrets. These are *not* real credentials to any exisiting systems. +{{< /note >}} + +## Review Existing Secrets in GCP Secret Manager + +Before migrating to OpenBao, evaluate how your organization currently uses GCP Secret Manager. + +For example, a web application might verify the signature of a JSON Web Token (JWT) using a secret key stored in GCP Secret Manager. Instead of hardcoding the secret in source code or container images, the application is granted a role that allows it to retrieve the secret at runtime. This protects the secret from being exposed through version control or CI/CD pipelines. + +OpenBao supports similar access workflows using dynamic injection, AppRole-based access control, and tight integration with Kubernetes workloads. + +{{< note type="warning" >}} +Ensure that you securely handle any exported secrets, as they no longer benefit from encryption by GCP Secret Manager. +{{< /note >}} + +### Review Secrets Using the GCP Console + +1. Navigate to **Security > Secret Manager** to list secrets: + + ![GCP Secret Manager UI showing list of stored secrets.](gcp-secret-manager-secret-list.png) + +1. Select a secret, open the latest version, and click **Actions > View secret value**: + + ![GCP Secret Manager UI displaying how to value of a selected secret.](gcp-secret-manager-secret-value.png) + +### Review Secrets Using the `gcloud` CLI + +You can also use the `gcloud` CLI to authenticate and inspect the secrets stored in GCP Secret Manager. + +1. Authenticate with the CLI: + + ```command + gcloud auth login + ``` + +1. Set the active project, replacing {{< placeholder "GCP_PROJECT_ID" >}} (e.g. `ecommerce-application-454116`) with your actual project ID: + + ```command + gcloud config set project {{< placeholder "GCP_PROJECT_ID" >}} + ``` + + **For Example**: + + ```command + gcloud config set project ecommerce-application-454116 + ``` + +1. [List](https://cloud.google.com/sdk/gcloud/reference/secrets/list) all secrets: + + ```command + gcloud secrets list + ``` + + ```output + NAME CREATED REPLICATION_POLICY LOCATIONS + billing_service_API_key 2025-03-01T12:25:36 automatic - + deploy_key 2025-02-28T04:04:58 automatic - + inventory_service_API_key 2024-11-15T16:35:35 automatic - + jwt-signing-secret 2025-03-08T12:01:30 automatic - + slack_webhook_url 2024-11-19T21:19:15 automatic - + ``` + +1. Retrieve the [latest version](https://cloud.google.com/sdk/gcloud/reference/secrets/versions/access) of a secret, replacing {{< placeholder "GCP_SECRET_NAME" >}} (e.g. `jwt-signing-secret`) with an actual secret name: + + ```command + gcloud secrets versions access latest --secret={{< placeholder "GCP_SECRET_NAME" >}} + ``` + + **For Example**: + + ```command + gcloud secrets versions access latest --secret=jwt-signing-secret + ``` + + ```output + EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW + ``` + +## Deploy OpenBao on Akamai Cloud + +When migrating from GCP Secret Manager to OpenBao on Akamai Cloud, your deployment requirements determine whether to install OpenBao on a single Linode Instance or to deploy it in a fault-tolerant environment using the Linode Kubernetes Engine (LKE). Follow the appropriate guide below: + +- [Deploying OpenBao on a Linode Instance](https://docs.google.com/document/d/1x30v1xT_EDuRNnhE9jv5VkFqj9Lo4N3kNO6ICOoSrOM/edit?usp=sharing) +- [Deploying OpenBao on Linode Kubernetes Engine](https://docs.google.com/document/d/1gS6hQg09Ufr1Ku0v528acLESnyj1ZpXTxLhkLIlP-u8/edit?usp=sharing) +- [Deploying OpenBao through the Linode Marketplace](/docs/marketplace-docs/guides/openbao/) + +Regardless of the method used, make sure that: + +- OpenBao is successfully initialized. +- The vault is unsealed. +- The `BAO_ADDR` environment variable is set. +- You are authenticated using the root token. + +Once these steps are complete, return to this guide to begin migrating secrets. + +### Create a Policy and AppRole + +To replicate GCP IAM-style access control, OpenBao provides AppRoles. For example, in GCP, a service might be granted a role like `JWTSigner` to retrieve a secret. In OpenBao, this same functionality is implemented using a policy-bound AppRole. + +Follow these steps to create an OpenBao AppRole that mimics the role-based access used in GCP IAM. + +#### Enable AppRole + +1. Enable the AppRole authentication method: + + ```command + bao auth enable approle + ``` + + ```output + Success! Enabled approle auth method at: approle/ + ``` + +#### Create a Policy + +2. Create a new `.hcl` [policy file](https://openbao.org/docs/concepts/policies/) in `/etc/openbao`, replacing {{< placeholder "POLICY_FILE" >}} (e.g. `jwt-secrets-policy.hcl`) with a policy filename of your choosing: + + ```command + sudo nano /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + sudo nano /etc/openbao/jwt-secrets-policy.hcl + ``` + +1. Give the file the following contents, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} (e.g. `jwt`) with your chosen mount path: + + ```file {title="POLICY_FILE.hcl"} + path "{{< placeholder "SECRET_MOUNT_PATH" >}}/*" { + capabilities = ["read"] + } + ``` + + **For Example**: + + ```file {title="jwt-secrets-policy.hcl"} + path "jwt/*" { + capabilities = ["read"] + } + ``` + + This policy grants read access to any secrets within the specified mount path. + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Add the policy to OpenBao, replacing {{< placeholder "POLICY_NAME" >}} (e.g. `jwt-secrets-policy`) and {{< placeholder "POLICY_FILE" >}}: + + ```command + bao policy write {{< placeholder "POLICY_NAME" >}} /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + bao policy write jwt-secrets-policy /etc/openbao/jwt-secrets-policy.hcl + ``` + + ```output + Success! Uploaded policy: jwt-secrets-policy + ``` + +#### Create an AppRole + +5. Create an AppRole for the application that needs access to the secret, replacing {{< placeholder "APPROLE_NAME" >}} (e.g. `app-authenticator-approle`) and {{< placeholder "POLICY_NAME" >}}: + + ```command + bao write \ + auth/approle/role/{{< placeholder "APPROLE_NAME" >}} \ + token_policies={{< placeholder "POLICY_NAME" >}} + ``` + + **For Example**: + + ```command + bao write \ + auth/approle/role/app-authenticator-approle \ + token_policies=jwt-secrets-policy + ``` + + ```output + Success! Data written to: auth/approle/role/app-authenticator-approle + ``` + +1. Verify that the AppRole was written successfully, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}} + ``` + + **For Example**: + + ```command + bao read auth/approle/role/app-authenticator-approle + ``` + + ```output + Key Value + --- ----- + bind_secret_id true + local_secret_ids false + secret_id_bound_cidrs + secret_id_num_uses 0 + secret_id_ttl 0s + token_bound_cidrs [] + token_explicit_max_ttl 0s + token_max_ttl 0s + token_no_default_policy false + token_num_uses 0 + token_period 0s + token_policies [jwt-secrets-policy] + token_strictly_bind_ip false + token_ttl 0s + token_type default + ``` + +1. Fetch the AppRole ID, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/role-id + ``` + + ```output + Key Value + --- ----- + role_id 019e2cc5-b8ce-4aa4-91b9-c2c9e9e59863 + ``` + +#### Generate a Secret ID + +8. Generate a secret ID for the role, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao write -f auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/secret-id + ``` + + **For Example**: + + ```command + bao write -f auth/approle/role/app-authenticator-approle/secret-id + ``` + + ```output + Key Value + --- ----- + secret_id cef786fb-1d1c-4c52-9466-aea47b3c8d3a + secret_id_accessor 373500ba-6922-4f91-b7f3-ec25f8253d1d + secret_id_num_uses 0 + secret_id_ttl 0s + ``` + +#### Generate an API Token + +9. Generate an API token for the AppRole, supplying the {{< placeholder "APPROLE_ID" >}} (e.g. `019e2cc5-b8ce-4aa4-91b9-c2c9e9e59863`) and {{< placeholder "APPROLE_SECRET_ID" >}} (e.g. `cef786fb-1d1c-4c52-9466-aea47b3c8d3a`) from the previous commands: + + ```command + bao write auth/approle/login \ + role_id="{{< placeholder "APPROLE_ID" >}}" \ + secret_id="{{< placeholder "APPROLE_SECRET_ID" >}}" + ``` + + **For Example**: + + ```command + bao write auth/approle/login \ + role_id="019e2cc5-b8ce-4aa4-91b9-c2c9e9e59863" \ + secret_id="cef786fb-1d1c-4c52-9466-aea47b3c8d3a" + ``` + + ```output + Key Value + --- ----- + token s.dy572yUtTNvHTZgIoxdNVO41 + token_accessor zT1TP281vORYSjysBiuMydht + token_duration 768h + token_renewable true + token_policies ["jwt-secrets-policy" "default"] + identity_policies [] + policies ["jwt-secrets-policy" "default"] + token_meta_role_name app-authenticator-approle + ``` + + The resulting AppRole token (e.g. `s.dy572yUtTNvHTZgIoxdNVO41`) can be used by a user, machine, or service, such as the authentication API for a web application, to authenticate OpenBao API calls, giving the caller authorization to read the JWT signing secret. + +### Storing Secrets + +Create the secret store defined in the policy created above. + +1. Enable the KV secrets engine, replacing {{< placeholder "SECRET_MOUNT_PATH" >}}: + + ```command + bao secrets enable --path={{< placeholder "SECRET_MOUNT_PATH" >}} kv + ``` + + **For Example**: + + ```command + bao secrets enable --path=jwt kv + ``` + + ```output + Success! Enabled the kv secrets engine at: jwt/ + ``` + +1. Store your {{< placeholder "SECRET_VALUE" >}} (e.g. `EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW`) in the {{< placeholder "SECRET_MOUNT_PATH" >}} as a secret named {{< placeholder "SECRET_NAME" >}} (e.g. `signer`): + + ```command + bao kv put --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} \ + "secret"="{{< placeholder "SECRET_VALUE" >}}" + ``` + + **For Example**: + + ```command + bao kv put --mount=jwt signer \ + "secret"="EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW" + ``` + + ```output + Success! Data written to: jwt/signer + ``` + +### Retrieving Secrets + +1. While authenticated with the root token, retrieve the secret using the OpenBao CLI, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} and {{< placeholder "SECRET_NAME" >}}: + + ```command + bao kv get --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} + ``` + + **For Example**: + + ```command + bao kv get --mount=jwt signer + ``` + + ```output + ====== Data ====== + Key Value + --- ----- + secret EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW + ``` + +1. Test access using the {{< placeholder "APPROLE_TOKEN" >}} (e.g. `s.dy572yUtTNvHTZgIoxdNVO41`) saved earlier, your {{< placeholder "SECRET_MOUNT_PATH" >}}, and the {{< placeholder "SECRET_NAME" >}}: + + ```command + curl --header "X-Vault-Token: {{< placeholder "APPROLE_TOKEN" >}}" \ + --request GET \ + $BAO_ADDR/v1/{{< placeholder "SECRET_MOUNT_PATH" >}}/{{< placeholder "SECRET_NAME" >}} \ + | jq + ``` + + **For Example**: + + ```command + curl --header "X-Vault-Token: s.dy572yUtTNvHTZgIoxdNVO41" \ + --request GET \ + $BAO_ADDR/v1/jwt/signer \ + | jq + ``` + + ```output + { + "request_id": "0e70b929-06b6-4685-b787-dc1ce6c31b9b", + "lease_id": "", + "renewable": false, + "lease_duration": 2764800, + "data": { + "secret": "EU&&7O^#c2GAMIdRyJlZkPEdoWKgy%CW" + }, + "wrap_info": null, + "warnings": null, + "auth": null + } + ``` + + The AppRole token can be used by applications or services to retrieve secrets through the OpenBao API. + + {{< note >}} + According to the [OpenBao API documentation](https://openbao.org/api-docs/libraries/), OpenBao is API-compatible with HashiCorp Vault. This means most Vault client libraries should also work with OpenBao, including: + + - [Go](https://github.com/hashicorp/vault/tree/main/api) + - [Ruby](https://github.com/hashicorp/vault-ruby) + - [C#](https://github.com/rajanadar/VaultSharp) + - [Java](https://developer.hashicorp.com/vault/api-docs/libraries#java) + - [Kotlin](https://github.com/kunickiaj/vault-kotlin) + - [Node.js](https://developer.hashicorp.com/vault/api-docs/libraries#node-js) + - [PHP](https://developer.hashicorp.com/vault/api-docs/libraries#php) + - [Python](https://github.com/hvac/hvac) + {{< /note >}} + +## Production Considerations + +When migrating from GCP Secret Manager to OpenBao on Akamai Cloud, it's important to ensure your deployment is secure, resilient, and optimized for performance. This section covers key security and high availability considerations to help you maintain a reliable and protected secrets management system. + +### Security + +For a production-grade OpenBao deployment, security should be a top priority. Protecting secrets from unauthorized access, ensuring secure communication, and enforcing strict access controls are essential to maintaining a secure environment. + +- **Access Control Policies**: Use OpenBao's [policy](https://openbao.org/docs/concepts/policies/) system to enforce RBAC. Define granular policies that only grant the necessary permissions, following the principle of least privilege. +- **Audit Logging**: Enable [detailed audit logs](https://openbao.org/docs/configuration/log-requests-level/) to track all access and modifications to secrets. OpenBao supports multiple logging backends, such as syslog and file-based logs, to help monitor suspicious activity. +- **Secrets Lifecycle Management**: Implement automated secrets rotation, revocation, and expiration to ensure secrets do not become stale or overexposed. Consider using dynamic secrets where possible to generate time-limited credentials. +- **Securing Network Communication**: Configure OpenBao to [use TLS to encrypt](https://openbao.org/docs/configuration/listener/tcp/#configuring-tls) all communications, ensuring data in transit remains secure. Regularly rotate TLS certificates to prevent expiration-related outages and reduce the risk of compromised certificates. + +### High Availability + +For production environments, OpenBao should be deployed with fault tolerance and scalability in mind. OpenBao’s [Autopilot mode](https://openbao.org/docs/concepts/integrated-storage/autopilot) for [high availability](https://openbao.org/docs/internals/high-availability/) ensures that if the active node fails, the cluster automatically elects a new leader, maintaining uptime without manual intervention. However, to enable seamless failover, organizations must configure their deployment correctly, and proactively monitor system health. + +- **Raft Storage Backend**: Use OpenBao’s [integrated storage](https://openbao.org/docs/internals/integrated-storage/), based on the [Raft protocol](https://thesecretlivesofdata.com/raft/), to enable distributed data replication across multiple nodes. This ensures data consistency and fault tolerance while reducing reliance on external storage backends. Configure regular Raft snapshots for disaster recovery. +- **Deploy Multiple Nodes**: OpenBao recommends at least five nodes for a [high-availability deployment](https://openbao.org/docs/concepts/ha/). The active node handles all requests, while standby nodes remain ready to take over in case of failure. +- **Monitor Leader Status**: Use [bao operator raft list-peers](https://openbao.org/docs/commands/operator/raft/#list-peers) to check the cluster’s leader and node statuses. This command helps ensure that standby nodes are correctly registered and ready for failover. \ No newline at end of file diff --git a/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/index.md b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/index.md new file mode 100644 index 00000000000..3aefd2119b9 --- /dev/null +++ b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/index.md @@ -0,0 +1,541 @@ +--- +slug: migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine +title: "Migrate From Oracle Vault to OpenBao on Akamai Cloud" +description: "Securely migrate secrets from Oracle Vault to OpenBao on Linode Kubernetes Engine (LKE), using Helm and AppRole-based access control." +authors: ["Akamai"] +contributors: ["Akamai"] +published: 2025-05-01 +keywords: ['oracle vault','openbao','migrate secrets from oci','openbao helm install','linode kubernetes engine','oke to openbao','bao kv put','bao approle authentication','open source vault alternative','manage secrets on lke'] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +external_resources: +- '[Oracle Vault Documentation](https://docs.oracle.com/en-us/iaas/Content/KeyManagement/Concepts/keyoverview.htm)' +- '[Oracle `oci` CLI Documentation](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm)' +- '[OpenBao Configuration Documentation](https://openbao.org/docs/configuration/)' +- '[OpenBao Integrated Storage](https://openbao.org/docs/concepts/integrated-storage/)' +--- + +Oracle Vault is a part of Oracle Cloud Infrastructure (OCI). It provides a secure, managed solution for storing and controlling access to sensitive information like API keys, passwords, and encryption keys. Oracle Vault is designed to integrate with other Oracle services, supporting features for key management, secret storage, and cryptographic functions. + +[OpenBao](https://openbao.org/) is an open source fork of [HashiCorp Vault](https://www.vaultproject.io/) that gives teams full control over how secrets are stored, encrypted, and accessed. Unlike managed platforms, OpenBao can be self-hosted in any environment, including on-premises and across multiple clouds. + +This guide walks through how to migrate secrets from Oracle Vault to OpenBao running on Akamai Cloud. + +## Before You Begin + +1. Follow our [Getting Started](https://techdocs.akamai.com/cloud-computing/docs/getting-started) guide to create an Akamai Cloud account if you do not already have one. + +1. Create a personal access token using the instructions in our [Manage personal access tokens](https://techdocs.akamai.com/cloud-computing/docs/manage-personal-access-tokens) guide. + +1. Install the Linode CLI using the instructions in the [Install and configure the CLI](https://techdocs.akamai.com/cloud-computing/docs/install-and-configure-the-cli) guide. + +1. Follow the steps in the *Install `kubectl`* section of the [Getting started with LKE](https://techdocs.akamai.com/cloud-computing/docs/getting-started-with-lke-linode-kubernetes-engine#install-kubectl) guide to install and configure `kubectl`. + +1. Ensure that you have access to your Oracle Cloud account with sufficient permissions to work with Oracle Vault. The [OCI CLI](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm) must also be installed and configured + +1. Install `jq`, a lightweight command line JSON processor. + +{{< note >}} +This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. +{{< /note >}} + +Additionally, this guide contains a number of placeholders that are intended to be replaced by your own unique values. The table below lists these placeholders, what they represent, and the example values used in this guide: + +| Placeholder | Represents | Example Value | +|------------------------------------------|------------------------------------------------------|-------------------------------------------------------------------| +| {{< placeholder "OCI_COMPARTMENT_ID" >}} | The OCID of the compartment containing your vault. | ocid1.compartment.oc1..aaaaaaaawrrlh7hw6b4tnsbxevyoywscike5ygn... | +| {{< placeholder "OCI_SECRET_ID" >}} | The OCID of the secret stored in Oracle Vault. | ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqaepiqln7ztj43ugit... | +| {{< placeholder "OCI_ENCODED_SECRET" >}} | The base64-encoded value of the Oracle secret. | eyAiYWNjZXNzX2tleV9pZCIgOiAiQUtJQTUxM0oyRERSQVhDRktYRjUi... | +| {{< placeholder "POLICY_FILE" >}} | The name of the policy file. | cloud-credentials-policy.hcl | +| {{< placeholder "SECRET_MOUNT_PATH" >}} | The mount path (namespace) where secrets are stored. | cloud-credentials | +| {{< placeholder "POLICY_NAME" >}} | The internal name for the policy in OpenBao. | cloud-credentials-policy | +| {{< placeholder "APPROLE_NAME" >}} | The name of the AppRole. | cloud-credential-reader-approle | +| {{< placeholder "APPROLE_ID" >}} | The role ID generated for the AppRole. | c8663988-136f-42de-af40-1dfb94f0c1f6 | +| {{< placeholder "APPROLE_SECRET_ID" >}} | The secret ID generated for the AppRole. | 9b9c27a3-dc27-4eea-921f-773164ec17c7 | +| {{< placeholder "SECRET_VALUE" >}} | The actual secret contents to store in OpenBao. | { "access_key_id": "...", "secret_access_key": "..." } | +| {{< placeholder "SECRET_NAME" >}} | The name of the secret stored under the mount path. | provider-a | +| {{< placeholder "APPROLE_TOKEN" >}} | The API token generated from the AppRole login. | s.36Yb3ijEOJbifprhdEiFtPhR | + +{{< note >}} +All of the example values used in this guide are purely examples to mimic the format of actual secrets. These are *not* real credentials to any exisiting systems. +{{< /note >}} + +## Review Existing Secrets in Oracle Vault + +Before migrating to OpenBao, evaluate how your organization currently uses Oracle Vault. + +For example, an application that accesses services from multiple cloud providers might retrieve access keys stored in Oracle Vault. Granting access at runtime ensures that credentials aren’t embedded in code or exposed during deployment. + +OpenBao supports equivalent secret injection workflows through AppRole and Kubernetes integration. + +{{< note type="warning" >}} +Ensure that you securely handle any exposed secrets, as they no longer benefit from encryption by Oracle Vault. +{{< /note >}} + +### Review Secrets Using the Oracle Console + +1. Navigate to **Security > Vault**, select your vault, and open the **Secrets** tab: + + ![Oracle Vault UI displaying secrets in selected vault.](oracle-vault-secret-list.png) + +1. Select a secret, go to the latest version, and click **View Secret Contents**: + + ![Oracle Vault showing how to view the content of a selected secret.](oracle-vault-secret-value.png) + +### Review Secrets Using the OCI CLI + +You can also use the Oracle Cloud CLI (`oci`) to manage the secrets in your Oracle Vault. + +1. Authenticate with the OCI CLI. You must have configured your API key, tenancy OCID, and user OCID. Run a basic command to confirm authentication: + + ```command + oci iam region list + ``` + +1. Identify the compartment that contains your vault: + + ```command + oci iam compartment list --query 'data[]["name","id"]' + ``` + + In the example above, the `credentials` vault belongs to the `web-application` compartment: + + ```output + [ + [ + "web-application", "ocid1.compartment.oc1..aaaaaaaawrrlh7hw6b4tnsbxevyoywscike5ygn4ut5n734mjsclijgpjjgq" + ] + ] + ``` + +1. [List the secrets in your vault](https://docs.oracle.com/en-us/iaas/tools/oci-cli/3.53.0/oci_cli_docs/cmdref/vault/secret/list.html) by specifying the {{< placeholder "OCI_COMPARTMENT_ID" >}} (e.g. `ocid1.compartment.oc1..aaaaaaaawrrlh7hw6b4tnsbxevyoywscike5ygn4ut5n734mjsclijgpjjgq`): + + ```command + oci vault secret list \ + --compartment-id {{< placeholder "OCI_COMPARTMENT_ID" >}} \ + --query 'data[].["secret-name","description","id"]' + ``` + + **For Example**: + + ```command + oci vault secret list \ + --compartment-id ocid1.compartment.oc1..aaaaaaaawrrlh7hw6b4tnsbxevyoywscike5ygn4ut5n734mjsclijgpjjgq \ + --query 'data[].["secret-name","description","id"]' + ``` + + ```output + [ + [ + "cloud_provider_a", + "Access key ID and secret access key for provider", + "ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqaepiqln7ztj43ugit75w3wl7kyzldk3rbqkfd2zmtp3ea" + ], + [ + "cloud_provider_b", + "Project ID and project API KEY", + "ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqacnhdzfprgd4f4ml7rpkjqmqlyz7p5kjjfinvyn57qdoa" + ], + [ + "cloud_provider_c", + "Client ID and client secret", + "ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqavn32ibazaqinya5bv3eyc4ndfvebcnksnqk4vl74xqqa" + ] + ] + ``` + +1. Retrieve the [value of a secret](https://docs.oracle.com/en-us/iaas/tools/oci-cli/3.53.0/oci_cli_docs/cmdref/secrets/secret-bundle/get.html) by specifying its {{< placeholder "OCI_SECRET_ID" >}} (e.g. `ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqaepiqln7ztj43ugit75w3wl7kyzldk3rbqkfd2zmtp3ea`): + + ```command + oci secrets secret-bundle get \ + --secret-id {{< placeholder "OCI_SECRET_ID" >}} \ + --stage CURRENT \ + --query 'data."secret-bundle-content"' + ``` + + **For Example**: + + ```command + oci secrets secret-bundle get \ + --secret-id ocid1.vaultsecret.oc1.phx.amaaaaaaogvqnkqaepiqln7ztj43ugit75w3wl7kyzldk3rbqkfd2zmtp3ea \ + --stage CURRENT \ + --query 'data."secret-bundle-content"' + ``` + + ```output + { + "content": + "eyAiYWNjZXNzX2tleV9pZCIgOiAiQUtJQTUxM0oyRERSQVhDRktYRjUiLCAic2VjcmV0X2FjY2Vzc19rZXkiIDoiWGRxRDBCUGE4YUxGYU4rRUk4U0FZbTlVNFpZZVhRZE1HQUlqS0QveCIgfQ==", + "content-type": "BASE64" + } + ``` + +1. If the secret bundle `content-type` is `BASE64` (e.g. `eyAiYWNjZXNzX2tleV9pZCIgOiAiQUtJQTUxM0oyRERSQVhDRktYRjUiLCAic2VjcmV0X2FjY2Vzc19rZXkiIDoiWGRxRDBCUGE4YUxGYU4rRUk4U0FZbTlVNFpZZVhRZE1HQUlqS0QveCIgfQ==`), you must decode it to reveal the original value: + + ```command + echo {{< placeholder "OCI_ENCODED_SECRET" >}} \ + | base64 --decode + ``` + + **For Example**: + + ```command + echo eyAiYWNjZXNzX2tleV9pZCIgOiAiQUtJQTUxM0oyRERSQVhDRktYRjUiLCAic2VjcmV0X2FjY2Vzc19rZXkiIDoiWGRxRDBCUGE4YUxGYU4rRUk4U0FZbTlVNFpZZVhRZE1HQUlqS0QveCIgfQ== \ + | base64 --decode + ``` + + ```output + { "access_key_id": "AKIA513J2DDRAXCFKXF5", "secret_access_key": "XdqD0BPa8aLFaN+EI8SAYm9U4ZYeXQdMGAIjKD/x" } + ``` + + {{< note >}} + You can also retrieve and decode the secret in a single command: + + ```command + oci secrets secret-bundle get \ + --secret-id {{< placeholder "OCI_SECRET_ID" >}} \ + --stage CURRENT \ + --query 'data."secret-bundle-content".content' \ + --raw-output \ + | base64 --decode + ``` + {{< /note >}} + +## Deploy OpenBao on Akamai Cloud + +When migrating from Oracle Vault to OpenBao on Akamai Cloud, your deployment requirements determine whether to install OpenBao on a single Linode Instance or to deploy it in a fault-tolerant environment using the Linode Kubernetes Engine (LKE). Follow the appropriate guide below: + +- [Deploying OpenBao on a Linode Instance](https://docs.google.com/document/d/1x30v1xT_EDuRNnhE9jv5VkFqj9Lo4N3kNO6ICOoSrOM/edit?usp=sharing) +- [Deploying OpenBao on Linode Kubernetes Engine](https://docs.google.com/document/d/1gS6hQg09Ufr1Ku0v528acLESnyj1ZpXTxLhkLIlP-u8/edit?usp=sharing) +- [Deploying OpenBao through the Linode Marketplace](/docs/marketplace-docs/guides/openbao/) + +Regardless of the method used, make sure that: + +- OpenBao is successfully initialized. +- The vault is unsealed. +- The `BAO_ADDR` environment variable is set. +- You are authenticated using the root token. + +### Create a Policy and AppRole + +To replicate Oracle IAM-style access control in OpenBao, use AppRoles. While Oracle Vault manages permissions through IAM policies instead of granular roles, OpenBao allows you to assign access through policy-bound AppRoles. + +Follow these steps to create an OpenBao AppRole that mirrors access controls used in Oracle IAM. + +#### Enable AppRole + +1. Enable the AppRole authentication method: + + ```command + bao auth enable approle + ``` + + ```output + Success! Enabled approle auth method at: approle/ + ``` + +#### Create a Policy + +2. Create a new `.hcl` [policy file](https://openbao.org/docs/concepts/policies/) in `/etc/openbao`, replacing {{< placeholder "POLICY_FILE" >}} (e.g. `cloud-credentials-policy.hcl`) with a policy filename of your choosing: + + ```command + sudo nano /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + sudo nano /etc/openbao/cloud-credentials-policy.hcl + ``` +1. Give the file the following contents, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} (e.g. `cloud-credentials`) with your chosen mount path: + + ```file {title="POLICY_FILE.hcl"} + path "{{< placeholder "SECRET_MOUNT_PATH" >}}/*" { + capabilities = ["read"] + } + ``` + + **For Example**: + + ```file {title="cloud-credentials-policy.hcl"} + path "cloud-credentials/*" { + capabilities = ["read"] + } + ``` + + This policy grants read access to any secrets within the specified mount path. + + When done, press CTRL+X, followed by Y then Enter to save the file and exit `nano`. + +1. Add the policy to OpenBao, replacing {{< placeholder "POLICY_NAME" >}} (e.g. `cloud-credentials-policy`) and {{< placeholder "POLICY_FILE" >}}: + + ```command + bao policy write {{< placeholder "POLICY_NAME" >}} /etc/openbao/{{< placeholder "POLICY_FILE" >}} + ``` + + **For Example**: + + ```command + bao policy write cloud-credentials-policy /etc/openbao/cloud-credentials-policy.hcl + ``` + + ```output + Success! Uploaded policy: cloud-credentials-policy + ``` + +#### Create an AppRole + +5. Create an AppRole for the application that needs access to the secret, replacing {{< placeholder "APPROLE_NAME" >}} (e.g. `cloud-credential-reader-approle`) and {{< placeholder "POLICY_NAME" >}}: + + ```command + bao write \ + auth/approle/role/{{< placeholder "APPROLE_NAME" >}} \ + token_policies={{< placeholder "POLICY_NAME" >}} + ``` + + **For Example**: + + ```command + bao write \ + auth/approle/role/cloud-credential-reader-approle \ + token_policies=cloud-credentials-policy + ``` + + ```output + Success! Data written to: auth/approle/role/cloud-credential-reader-approle + ``` + +1. Verify that the AppRole was written successfully, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}} + ``` + + **For Example**: + + ```command + bao read auth/approle/role/cloud-credential-reader-approle + ``` + + ```output + Key Value + --- ----- + bind_secret_id true + local_secret_ids false + secret_id_bound_cidrs + secret_id_num_uses 0 + secret_id_ttl 0s + token_bound_cidrs [] + token_explicit_max_ttl 0s + token_max_ttl 0s + token_no_default_policy false + token_num_uses 0 + token_period 0s + token_policies [cloud-credentials-secrets-policy] + token_strictly_bind_ip false + token_ttl 0s + token_type default + ``` + +1. Fetch the AppRole ID, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao read auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/role-id + ``` + + **For Example**: + + ```command + bao read auth/approle/role/cloud-credential-reader-approle/role-id + ``` + + ```output + Key Value + --- ----- + role_id c8663988-136f-42de-af40-1dfb94f0c1f6 + ``` + +#### Generate a Secret ID + +8. Generate a secret ID for the role, replacing {{< placeholder "APPROLE_NAME" >}}: + + ```command + bao write -f auth/approle/role/{{< placeholder "APPROLE_NAME" >}}/secret-id + ``` + + **For Example**: + + ```command + bao write -f auth/approle/role/cloud-credential-reader-approle/secret-id + ``` + + ```output + Key Value + --- ----- + secret_id 9b9c27a3-dc27-4eea-921f-773164ec17c7 + secret_id_accessor 20abfad4-029f-45e8-a749-ecc041ff3554 + secret_id_num_uses 0 + secret_id_ttl 0s + ``` + +#### Generate an API Token + +9. Generate an API token for the AppRole, supplying the {{< placeholder "APPROLE_ID" >}} (e.g. `c8663988-136f-42de-af40-1dfb94f0c1f6`) and {{< placeholder "APPROLE_SECRET_ID" >}} (e.g. `9b9c27a3-dc27-4eea-921f-773164ec17c7`) from the previous commands: + + ```command + bao write auth/approle/login \ + role_id="{{< placeholder "APPROLE_ID" >}}" \ + secret_id="{{< placeholder "APPROLE_SECRET_ID" >}}" + ``` + + **For Example**: + + ```command + bao write auth/approle/login \ + role_id="c8663988-136f-42de-af40-1dfb94f0c1f6" \ + secret_id="9b9c27a3-dc27-4eea-921f-773164ec17c7" + ``` + + ```output + Key Value + --- ----- + token s.Q9n7KPnLKSDoYnVdrHnphEml + token_accessor LkSCfmBQVCfL8s2eX4EfnqO4 + token_duration 768h + token_renewable true + token_policies ["cloud-credentials-secrets-policy" "default"] + identity_policies [] + policies ["cloud-credentials-secrets-policy" "default"] + token_meta_role_name cloud-credential-reader-approle + ``` + + The resulting AppRole token (e.g. `s.Q9n7KPnLKSDoYnVdrHnphEml`) can be used by a user, machine, or service, such as an infrastructure management application, to authenticate OpenBao API calls, giving the caller authorization to read the cloud provider credentials secrets. + +### Storing Secrets + +Create the secret store defined in the policy created above. + +1. Enable the KV secrets engine, replacing {{< placeholder "SECRET_MOUNT_PATH" >}}: + + ```command + bao secrets enable --path={{< placeholder "SECRET_MOUNT_PATH" >}} kv + ``` + + **For Example**: + + ```command + bao secrets enable --path=cloud-credentials kv + ``` + + ```output + Success! Enabled the kv secrets engine at: cloud-credentials/ + ``` + +1. Store your {{< placeholder "SECRET_VALUE" >}} (e.g. `{ "access_key_id": "AKIA513J2DDRAXCFKXF5", "secret_access_key": "XdqD0BPa8aLFaN+EI8SAYm9U4ZYeXQdMGAIjKD/x" }`) in the {{< placeholder "SECRET_MOUNT_PATH" >}} as a secret named {{< placeholder "SECRET_NAME" >}} (e.g. `provider-a`): + + ```command + bao kv put --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} \ + "secret"="{{< placeholder "SECRET_VALUE" >}}" + ``` + + **For Example**: + + ```command + bao kv put --mount=cloud-credentials provider-a \ + "secret"="{ "access_key_id": "AKIA513J2DDRAXCFKXF5", "secret_access_key": "XdqD0BPa8aLFaN+EI8SAYm9U4ZYeXQdMGAIjKD/x" }" + ``` + + ```output + Success! Data written to: cloud-credentials/provider-a + ``` + +### Retrieving Secrets + +1. While authenticated with the root token, retrieve the secret using the OpenBao CLI, replacing {{< placeholder "SECRET_MOUNT_PATH" >}} and {{< placeholder "SECRET_NAME" >}}: + + ```command + bao kv get --mount={{< placeholder "SECRET_MOUNT_PATH" >}} {{< placeholder "SECRET_NAME" >}} + ``` + + **For Example**: + + ```command + bao kv get --mount=cloud-credentials provider-a + ``` + + ```output + ====== Data ====== + Key Value + --- ----- + access_key_id AKIA513J2DDRAXCFKXF5 + secret_access_key XdqD0BPa8aLFaN+EI8SAYm9U4ZYeXQdMGAIjKD/x + ``` + +1. Test access using the {{< placeholder "APPROLE_TOKEN" >}} (e.g. `s.36Yb3ijEOJbifprhdEiFtPhR`) saved earlier, your {{< placeholder "SECRET_MOUNT_PATH" >}}, and the {{< placeholder "SECRET_NAME" >}}: + + ```command + curl --header "X-Vault-Token: {{< placeholder "APPROLE_TOKEN" >}}" \ + --request GET \ + $BAO_ADDR/v1/{{< placeholder "SECRET_MOUNT_PATH" >}}/{{< placeholder "SECRET_NAME" >}} \ + | jq + ``` + + **For Example**: + + ```command + curl --header "X-Vault-Token: s.36Yb3ijEOJbifprhdEiFtPhR" \ + --request GET \ + $BAO_ADDR/v1/cloud-credentials/provider-a \ + | jq + ``` + + ```output + { + "request_id": "92c5026e-bb14-4e2a-8d70-e94fb005183f", + "lease_id": "", + "renewable": false, + "lease_duration": 2764800, + "data": { + "access_key_id": "AKIA513J2DDRAXCFKXF5", + "secret_access_key": "XdqD0BPa8aLFaN+EI8SAYm9U4ZYeXQdMGAIjKD/x" + }, + "wrap_info": null, + "warnings": null, + "auth": null + } + ``` + + The AppRole token can be used by applications or services to retrieve secrets through the OpenBao API. + + {{< note >}} + According to the [OpenBao API documentation](https://openbao.org/api-docs/libraries/), OpenBao is API-compatible with HashiCorp Vault. This means most Vault client libraries should also work with OpenBao, including: + + - [Go](https://github.com/hashicorp/vault/tree/main/api) + - [Ruby](https://github.com/hashicorp/vault-ruby) + - [C#](https://github.com/rajanadar/VaultSharp) + - [Java](https://developer.hashicorp.com/vault/api-docs/libraries#java) + - [Kotlin](https://github.com/kunickiaj/vault-kotlin) + - [Node.js](https://developer.hashicorp.com/vault/api-docs/libraries#node-js) + - [PHP](https://developer.hashicorp.com/vault/api-docs/libraries#php) + - [Python](https://github.com/hvac/hvac) + {{< /note >}} + +## Production Considerations + +When migrating from Oracle Vault to OpenBao on Akamai Cloud, it's important to ensure your deployment is secure, resilient, and optimized for performance. This section covers key security and high availability considerations to help you maintain a reliable and protected secrets management system. + +### Security + +For a production-grade OpenBao deployment, security should be a top priority. Protecting secrets from unauthorized access, ensuring secure communication, and enforcing strict access controls are essential to maintaining a secure environment. + +- **Access Control Policies**: Use OpenBao's [policy](https://openbao.org/docs/concepts/policies/) system to enforce RBAC. Define granular policies that grant only the necessary permissions, following the principle of least privilege. +- **Audit Logging**: Enable [detailed audit logs](https://openbao.org/docs/configuration/log-requests-level/) to track all access and modifications to secrets. OpenBao supports multiple logging backends, such as syslog and file-based logs, to help monitor suspicious activity. +- **Secrets Lifecycle Management**: Implement automated secrets rotation, revocation, and expiration to ensure secrets do not become stale or overexposed. Consider using dynamic secrets where possible to generate time-limited credentials. +- **Securing Network Communication**: Configure OpenBao to [use TLS to encrypt](https://openbao.org/docs/configuration/listener/tcp/#configuring-tls) all communications, ensuring data in transit remains secure. Regularly rotate TLS certificates to prevent expiration-related outages and reduce the risk of compromised certificates. + +### High Availability + +For production environments, OpenBao should be deployed with fault tolerance and scalability in mind. OpenBao’s [Autopilot mode](https://openbao.org/docs/concepts/integrated-storage/autopilot) for [high availability](https://openbao.org/docs/internals/high-availability/) ensures that if the active node fails, the cluster automatically elects a new leader, maintaining uptime without manual intervention. However, to enable seamless failover, organizations must configure their deployment correctly, and proactively monitor system health. + +- **Raft Storage Backend**: Use OpenBao’s [integrated storage](https://openbao.org/docs/internals/integrated-storage/), based on the [Raft protocol](https://thesecretlivesofdata.com/raft/), to enable distributed data replication across multiple nodes. This ensures data consistency and fault tolerance while reducing reliance on external storage backends. Configure regular Raft snapshots for disaster recovery. +- **Deploy Multiple Nodes**: OpenBao recommends at least five nodes for a [high-availability deployment](https://openbao.org/docs/concepts/ha/). The active node handles all requests, while standby nodes remain ready to take over in case of failure. +- **Monitor Leader Status**: Use [`bao operator raft list-peers`](https://openbao.org/docs/commands/operator/raft/#list-peers) to check the cluster’s leader and node statuses. This command helps ensure that standby nodes are correctly registered and ready for failover. \ No newline at end of file diff --git a/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-list.png b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-list.png new file mode 100644 index 00000000000..b0150cf42a0 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-list.png differ diff --git a/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-value.png b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-value.png new file mode 100644 index 00000000000..8d7f6f7d134 Binary files /dev/null and b/docs/guides/kubernetes/migrate-from-oracle-vault-to-openbao-on-linode-kubernetes-engine/oracle-vault-secret-value.png differ