Instance Vault

Before getting started, you will need to ensure that you have an Ascend Instance. If you do not already have an instance, you can request an instance.

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.
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.
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 Instance. You can do this by running the following commands in your terminal:

az login
az ad app create --display-name "ascend-instance"

2. You can also create an app registration for your Ascend Environment using the following command. This app will be used when setting up your Environment Vault.

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

3. You will need to provide both the Environment and Instance App IDs and your Azure Tenant ID to your Ascend representative to configure the Ascend Instance 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 and Environment 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 instance settings (Ascend.io Instance: <instance-name> -> Settings -> Instance)
2. Under Instance Vault, 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 Instance application registration into your Azure Active Directory

az ad sp create --id "<ascend-instance-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 instance, 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-instance-azure-client-id>" --parameters '{
  "name": "ascend-kubernetes-instance",
  "issuer": "<the OIDC issuer for your cluster>",
  "description": "Grant access to the instance 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 Instance app registration on the Azure Key Vault

az role assignment create \
  --role "Key Vault Secrets Officer" \
  --assignee "<ascend-instance-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 instance settings (Ascend.io Instance: <instance-name> -> Settings -> Instance)
2. Under Instance Vault, 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 instance secrets

Using a secrets prefix

Ascend recommends having a separate GCP Project for your Instance and 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 instance

gcloud projects add-iam-policy-binding <your-project-id> \
  --member="serviceAccount:<ascend-instance-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 instance, 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-instance-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 Instance Vault, you can set up your Instance Store.