Environment Vault

Setting up your Environment Vaults is almost identical to setting up your Instance Vaults. You will need to create a vault in your desired cloud provider and grant the Service Principal associated with your Ascend Environment access to it.

Before you get started, you will need to make sure you have already set up your Instance Vault and Instance Store.

Azure Key Vault

When setting up an Azure Key Vault, you will need to grant permissions to a Service Principal that Ascend will use to access your vault. You can do this in two ways:

• Using an Ascend-Managed Identity where you grant Ascend's multi-tenant application access to your vault.
• Using a User-provided Identity where you will need to create an Azure AD App Registration and provide the credentials to Ascend.

Which to choose?

While Ascend-Managed Identity is the recommended approach as it requires fewer steps, it does require the user have the Cloud Application Administrator role and some organizations may restrict users from adding a multi-tenant application to their Azure AD. User-provided Identity may be a better option for users who do not have the necessary permissions.

Ascend-Managed Identity

Prerequisites

1. You will need to install the Azure CLI on your local machine (follow these instructions to install the Azure CLI).
2. Ensure that you are logged in to the Azure CLI on your local machine by running az login in your terminal.
3. You will need a Resource Group where you will create your vaults. Follow these instructions to create a resource group in Azure. This can be the same resource group you created for your Instance Vault.
4. You will need at least a Cloud Application Administrator role for registering the service principal for the Ascend application
5. You will need permission to create role assignments to grant the Ascend application access to the vaults.
6. You will need to ensure you have Microsoft.KeyVault/vaults/write permissions in your resource group. You can choose to use the Contributor role or the Key Vault Contributor role to ensure you have the right permissions.

User-Provided Identity

Prerequisites

1. You will need to install the Azure CLI on your local machine (follow these instructions to install the Azure CLI). Please ensure you have version 2.39.0 or later of the Azure CLI. You can verify this by running az --version.
2. Ensure you are logged in to the Azure CLI on your local machine by running az login in your terminal.
3. You will need a Resource Group where you will create your vaults. Follow these instructions to create a resource group in Azure. This can be the same resource group you created for your Instance Vault.
4. You will need permission to create role assignments to grant the Ascend application access to the vaults.
5. You will need to ensure you have Microsoft.KeyVault/vaults/write permissions in your resource group. You can choose to use the Contributor role or the Key Vault Contributor role to ensure you have the right permissions.

Create an App Registration

1. You must create an app registration for the Ascend Environment. You can do this by running the following commands in your terminal. If you already completed this step as part of Instance Vault setup, you can skip directly to creating your environment vault and granting Ascend access:

az login
az ad app create --display-name "ascend-environment-prod"

2. You will need to provide the App IDs and your Azure Tenant ID to your Ascend representative to configure the Ascend Environment to start authenticating to Azure using these identities. To get the App IDs and Tenant ID, run the following commands in your terminal:

az ad app list --query "[?contains(displayName, 'ascend')].{AppID:appId, DisplayName:displayName}" --output table
az account show --query 'tenantId'

Before Proceeding

Before you can move forward with the next steps, Ascend will need to configure your Ascend Instance to use the provided App Registrations. A representative will reach out to you once this step has been completed and you can move forward.

Create your Azure Key Vault and Grant Access to Ascend

1. In the Ascend UI, navigate to the environment settings (Ascend.io Instance: <instance-name> -> Settings -> Environments -> Environment: <environment-name>)
2. Under Environment Vault, select your Environment (your Instance comes with a prod environment by default). Select Azure Key Vault.
3. Fill in the following details. These values are used to generate the script you will run in the next step:
   • The Resource Group Name where your Azure Key Vault will be created.
   • The Subscription ID.
   • A name for the Azure Key Vault that will be created.
4. Click Get Setup Script button and run the script in your terminal.
5. Click Check and Add Vault

What does this script do?

• (Ascend-Managed Identity only) Installs the Ascend Environment application registration into your Azure Active Directory

az ad sp create --id "<ascend-environment-azure-client-id>"

• Creates an Azure Key Vault in your Azure subscription

az keyvault create \
  --name "<your-azure-key-vault-name>" \
  --enable-rbac-authorization \
  --resource-group "<your-resource-group>"

• (User-Provided Identity only) This command creates a federated credential for the Azure Application ID you provided for your environment, allowing it to authenticate via an OIDC issuer from the Ascend Kubernetes service account to enable secure access to your vault.

az ad app federated-credential create --id "<ascend-environment-azure-client-id>" --parameters '{
  "name": "ascend-kubernetes-environment-prod",
  "issuer": "<the OIDC issuer for your cluster>",
  "description": "Grant access to the environment-prod service account in the <your-instance> Ascend instance (running at <your-insance>.api-dev.ascend.io)",
  "subject": "<your-service-account-name>",
  "audiences": ["api://AzureADTokenExchange"]
}'

• Grants the 'Key Vault Secrets Officer' role to the Ascend Environment app registration on the Azure Key Vault

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee "<ascend-environment-azure-client-id>" \
  --scope "/subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-key-vault-name>"

GCP Secret Manager

Prerequisites

1. You will need to install the Google Cloud CLI on your local machine, following the instructions here. You can also use Google Cloud Shell to run the commands in this section.
2. You will need a Google Cloud Project with the Secret Manager API is enabled (follow these instructions to enable Secret Manager in your Google Cloud Project).
3. You will need to ensure you have permissions to create custom roles in your GCP Project. You will either need to be a Owner on the project, or ensure you are assigned the following roles:

• Project Editor (roles/editor)
• Role Administrator (roles/iam.roleAdmin)
• Project IAM Admin (roles/resourcemanager.projectIamAdmin)

Grant Ascend Access to Google Secret Manager

1. Navigate to the Environment settings (Ascend.io Instance: <instance-name> -> Settings -> Environments -> Environment: <environment-name>)
2. Under Environment Vault, select your Environment (your Instance comes with a prod environment by default). Select Google Cloud Secret Manager
3. Fill in the following details. These values are used to generate the script you will run in the next step:
   • Your Google Cloud Project ID
   • (Optional) A prefix to differentiate environment secrets

Using a secrets prefix

Ascend recommends having a separate GCP Project for each Environment. However, you can choose to store both Instance and Environment secrets in the same project. If you choose to do this, you must choose a prefix to differentiate Instance and Environment secrets.

4. Click Get Setup Script button and run the script in your terminal.
5. Click Check and Add Vault

What does this script do?

• Enables the Secret Manager API in your Google Cloud Project

gcloud config set project <your-project-id>
gcloud services enable secretmanager.googleapis.com

• Creates a custom role in your Google Cloud Project that just gives listing permissions

gcloud iam roles create ascendSecretLister \
  --project=<your-project-id> \
  --title="Ascend Secret Lister" \
  --description="Custom role for Ascend to list secrets in GCP Secret Manager" \
  --stage="GA" \
  --permissions="secretmanager.secrets.list"

• Grants the custom role to the GCP service account associated with your Ascend Environment

gcloud projects add-iam-policy-binding  <your-project-id> \
  --member="serviceAccount:<ascend-environment-gcp-service-account>" \
  --role="projects/<your-project-id>/roles/ascendSecretLister" \
  --condition=None

• Grants the Secret Accessor role to the GCP service account associated with your Ascend Environment, and if you specified a prefix, the Secret Accessor role will be granted conditionally based on the prefix.

gcloud projects add-iam-policy-binding  <your-project-id> \
  --member="serviceAccount:<ascend-environment-gcp-service-account>" \
  --role="roles/secretmanager.secretAccessor" \
  --condition=title=prefixFilter,expression=resource.name.startsWith('projects/<your-project-number>/secrets/<your-secret-prefix>')"

Next Steps

Now that you have set up your Environment Vault to store environment secrets, you can set up your Environment Dataplane.