diff --git a/docs/guides/azure-federation.md b/docs/guides/azure-federation.md new file mode 100644 index 0000000000000..325991e9f4359 --- /dev/null +++ b/docs/guides/azure-federation.md @@ -0,0 +1,131 @@ +# Federating Coder's control plane to Azure + +
+January 26, 2024 + +--- + +This guide will walkthrough how to authenticate a Coder Provisioner to Microsoft +Azure, using a Service Principal with a client certificate. You can use this +guide for authenticating Coder to Azure, regardless of where Coder is run, +either on-premise or in a non-Azure cloud. This method is one of several +[recommended by Terraform](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs#authenticating-to-azure). + +## Step 1: Generate Client Certificate & PKCS bundle + +We'll need to create the certificate Coder will use for authentication. Run the +below command to generate a private key and self-signed certificate: + +```console +openssl req -subj '/CN=myclientcertificate/O=MyCompany, Inc./ST=CA/C=US' \ + -new -newkey rsa:4096 -sha256 -days 730 -nodes -x509 -keyout client.key -out client.crt +``` + +Next, generate a `.pfx` file to be used by Coder's Provisioner to authenticate +the AzureRM provider: + +```console +openssl pkcs12 -export -password pass:"Pa55w0rd123" -out client.pfx -inkey client.key -in client.crt +``` + +## Step 2: Create Azure Application & Service Principal + +Navigate to the Azure portal, and into the Microsoft Entra ID section. Select +the App Registration blade, and register a new application. Fill in the +following fields: + +- **Name**: this is a friendly identifier and can be anything (e.g. "Coder") +- **Supported Account Types**: - set to "Accounts in this organizational + directory only (single-tenant)" + +The **Redirect URI** field does not need to be set in this case. Take note of +the `Application (client) ID` and `Directory (tenant) ID` values, which will be +used by Coder. + +## Step 3: Assign Client Certificate to the Azure Application + +To upload the certificate we created in Step 1, select **Certificates & +secrets** on the left-hand side, and select **Upload Certificate**. Upload the +public key file, which is `service-principal.crt` from the example above. + +## Step 4: Set Permissions on the Service Principal + +Now that the Application is created in Microsoft Entra ID, we need to assign +permissions to the Service Principal so it can provision Azure resources for +Coder users. Navigate to the Subscriptions blade in the Azure Portal, select the +**Subscription > Access Control (IAM) > Add > Add role assignment**. + +Set the **Role** that grants the appropriate permissions to create the Azure +resources you need for your Coder workspaces. `Contributor` will provide +Read/Write on all Subscription resources. For more information on the available +roles, see the +[Microsoft documentation](https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles). + +## Step 5: Configure Coder to use the Client Certificate + +Now that the client certificate is uploaded to Azure, we need to mount the +certificate files into the Coder deployment. If running Coder on Kubernetes, you +will need to create the `.pfx` file as a Kubernetes secret, and mount it into +the Helm chart. + +Run the below command to create the secret: + +```console +kubectl create secret generic -n coder azure-client-cert-secret --from-file=client.pfx=/path/to/your/client.pfx +``` + +In addition, create secrets for each of the following values from your Azure +Application: + +- Client ID +- Tenant ID +- Subscription ID +- Certificate password + +Next, set the following values in Coder's Helm chart: + +```yaml +coder: + env: + - name: ARM_CLIENT_ID + valueFrom: + secretKeyRef: + key: id + name: arm-client-id + - name: ARM_CLIENT_CERTIFICATE_PATH + value: /home/coder/az/ + - name: ARM_CLIENT_CERTIFICATE_PASSWORD + valueFrom: + secretKeyRef: + key: password + name: arm-client-cert-password + - name: ARM_TENANT_ID + valueFrom: + secretKeyRef: + key: id + name: arm-tenant-id + - name: ARM_SUBSCRIPTION_ID + valueFrom: + secretKeyRef: + key: id + name: arm-subscription-id + volumes: + - name: "azure-client-cert" + secret: + secretName: "azure-client-cert-secret" + volumeMounts: + - name: "azure-client-cert" + mountPath: "/home/coder/az/" + readOnly: true +``` + +Upgrade the Coder deployment using the following `helm` command: + +```console +helm upgrade coder coder-v2/coder -n coder -f values.yaml +``` diff --git a/docs/manifest.json b/docs/manifest.json index 49a58e362d93c..abc19e86aff95 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1045,6 +1045,11 @@ "title": "Template ImagePullSecrets", "description": "Creating ImagePullSecrets for private registries", "path": "./guides/image-pull-secret.md" + }, + { + "title": "Azure Federation", + "description": "Federating Coder to Azure", + "path": "./guides/azure-federation.md" } ] }