> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/integrations/integrations-overview/azure-integration.md).

# Cloud integrations (Azure)

The first step in building out a self-hosted cluster in Azure.

To connect Release to your Microsoft Azure account, you need to create a service principal and configure credentials. You will then use these credentials to authenticate with Release and create a cloud integration.

You can set up the service principal using either the **Azure Portal** (recommended for beginners) or the **Azure CLI** (faster for experienced users).

## Option 1: Set up a service principal in the Azure Portal

Log in to the [Azure Portal](https://portal.azure.com) and navigate to **Microsoft Entra ID** (formerly Azure Active Directory).

#### Create an App Registration

1. In the left sidebar, select **App registrations** and click **New registration**
2. Under application details:
   * Give the application a name, such as "Release Service Principal"
   * Under **Supported account types**, select "Accounts in this organizational directory only (Default Directory only - Single tenant)"
   * Leave the Redirect URI blank (optional)
3. Click **Register** to create the app registration

![Screenshot: Create app registration](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e15976f87568d151e3d92e06472b027f6a76a4de%2Fazure-integration-app-registration.png?alt=media)

After registration, you'll see the application overview page. Take note of the following values as you'll need them later:

* **Application (client) ID**
* **Directory (tenant) ID**

#### Create a Client Secret

1. In the left sidebar of your app registration, select **Certificates & secrets**
2. Under **Client secrets**, click **New client secret**
3. Add a description (e.g., "Release Integration") and select an expiration period
4. Click **Add**
5. **Important**: Copy the **Value** immediately. This is your `client_secret` and will only be shown once. If you lose it, you'll need to create a new secret.

![Screenshot: Create client secret](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-f90c1d933f9e39ae46f3d5314c1d68fefbc4bf00%2Fazure-integration-client-secret.png?alt=media)

After clicking **Add**, the secret will be created and displayed. Copy the **Value** immediately:

![Screenshot: Client secret created](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-c51f43d26602674208ee534060861d5a3b7a412f%2Fazure-integration-client-secret-2.png?alt=media)

#### Assign Subscription Role

To allow Release to manage resources in your subscription, you need to assign the service principal the appropriate role:

1. Navigate to **Subscriptions** in the Azure Portal (search for "Subscriptions" in the top search bar)
2. Select the subscription you want to use with Release
3. Take note of your **Subscription ID** - you'll need this for the credentials file
4. In the left sidebar, select **Access control (IAM)**
5. Click **Add** > **Add role assignment**
6. Under the **Role** tab, select **Contributor** (or a more restrictive custom role based on your security requirements)
7. Click **Next** to go to the **Members** tab
8. Under **Assign access to**, select **User, group, or service principal**
9. Click **Select members** and search for your application name (e.g., "Release Service Principal")
10. Select your application and click **Select**
11. Click **Review + assign** to complete the role assignment

![Screenshot: Select role](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-4017df979cb05a298da603055b2c2b9d28a59140%2Fazure-integration-role-assignment.png?alt=media)

After selecting the Contributor role, click **Next** to select the members. Click **Select members** and search for your service principal:

![Screenshot: Select members](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-2c48843a801a06a4111b59f13904c9d1cd80c0bf%2Fazure-integration-role-assignment-2.png?alt=media)

After selecting your service principal, click **Select** and then **Review + assign**:

![Screenshot: Member selected](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-766b4787bf9cd953caa82502827cec772b1c6b46%2Fazure-integration-role-assignment-3.png?alt=media)

#### Create Credentials JSON File

Create a JSON file with the credentials you collected. The file should have the following format:

```json
{
  "subscription_id": "your-subscription-id",
  "tenant_id": "your-tenant-id",
  "client_id": "your-application-client-id",
  "client_secret": "your-client-secret-value"
}
```

Replace the placeholder values with the actual values from your Azure setup:

* `subscription_id`: The Subscription ID from your Azure subscription
* `tenant_id`: The Directory (tenant) ID from your app registration overview
* `client_id`: The Application (client) ID from your app registration overview
* `client_secret`: The secret value you copied when creating the client secret

Save this file locally as `azure-credentials.json` or similar.

## Option 2: Set up a service principal using Azure CLI

If you have the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) installed, you can create the service principal with a single command.

### Prerequisites

1. Install the Azure CLI
2. Log in to your Azure account:

   ```bash
   az login
   ```

### Create Service Principal with Role Assignment

Run the following command to create a service principal with the Contributor role on your subscription:

```bash
az ad sp create-for-rbac \
  --name "Release Service Principal" \
  --role Contributor \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID
```

Replace `YOUR_SUBSCRIPTION_ID` with your actual subscription ID. You can find your subscription ID by running:

```bash
az account show --query id --output tsv
```

### Save the Output

The `create-for-rbac` command will output JSON credentials similar to this:

```json
{
  "appId": "12345678-1234-1234-1234-123456789abc",
  "displayName": "Release Service Principal",
  "password": "your-client-secret-here",
  "tenant": "87654321-4321-4321-4321-cba987654321"
}
```

**Important**: Save this output immediately - the password (client secret) cannot be retrieved later.

### Format Credentials for Release

Convert the Azure CLI output to the format Release expects by creating a JSON file with the following structure:

```json
{
  "subscription_id": "YOUR_SUBSCRIPTION_ID",
  "tenant_id": "87654321-4321-4321-4321-cba987654321",
  "client_id": "12345678-1234-1234-1234-123456789abc",
  "client_secret": "your-client-secret-here"
}
```

Map the values as follows:

* `subscription_id`: Your Azure subscription ID (from `az account show`)
* `tenant_id`: The `tenant` value from the CLI output
* `client_id`: The `appId` value from the CLI output
* `client_secret`: The `password` value from the CLI output

Save this file as `azure-credentials.json`.

## Create a Release integration with Azure

First, navigate to the Account Settings screen by clicking the Account Settings icon in the upper right corner of the window.

On the **Configuration** screen, select the **Cloud Integrations** tab and click the **Create Cloud Integration** button:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-7c29cc1c73c8eed8a700ab0caf9fd34d3fec875f%2Fcreate-new-integration.png?alt=media)

Choose "Microsoft" or "Microsoft Azure" from the dropdown list of providers and give it a name based on what you plan to use it for (for example, "Production Azure"). Click **Choose File** to upload the JSON credentials file that you created.

Click **Create Cloud Integration** to save your settings.

### Verifying the Integration

After creating the integration, Release will validate your credentials by:

* Verifying access to the Azure subscription
* Checking that required resource providers are available

If validation fails, double-check that:

* All four credential values are correct in your JSON file
* The service principal has been assigned the Contributor role on your subscription
* The client secret hasn't expired

## Next Steps

Once your Azure cloud integration is configured, you can:

* Connect existing AKS (Azure Kubernetes Service) clusters to Release
* Use Azure Container Registry (ACR) for container images
* Deploy applications to your Azure infrastructure

For more information about using Azure with Release, see the main integrations documentation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/integrations/integrations-overview/azure-integration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.