From 5451071bf096c2cd539a406a1ee48f679fcb3207 Mon Sep 17 00:00:00 2001 From: Eric Date: Fri, 26 Jan 2024 21:52:21 +0000 Subject: [PATCH 1/3] docs: add guide for azure federation --- docs/guides/azure-federation.md | 134 ++++++++++++++++++++++++++++++++ docs/manifest.json | 5 ++ 2 files changed, 139 insertions(+) create mode 100644 docs/guides/azure-federation.md diff --git a/docs/guides/azure-federation.md b/docs/guides/azure-federation.md new file mode 100644 index 0000000000000..2212da2614934 --- /dev/null +++ b/docs/guides/azure-federation.md @@ -0,0 +1,134 @@ +# Federating Coder's control plane to Azure + +
+ + Eric Paulsen + + +
+January 26, 2024 + +--- + +This guide will walkthrough how to authenticate Coder's Terraform runner 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 Terraform runner 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 +``` + +Next, set the following values in Coder's Helm chart: + +```yaml +coder: + 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 +``` + +## Step 5: Configure your Template to use the Client Certificate + +Now that the client certificate is added to Coder, it can be used by Terraform +to authenticate to Azure. Set the below arguments in your AzureRM provider block +in the workspace template: + +```hcl +variable "client_id" { + sensitive = true +} +variable "tenant_id" { + sensitive = true +} +variable "subscription_id" { + sensitive = true +} +variable "client_cert_path" { + sensitive = true +} +variable "client_cert_password" { + sensitive = true +} + +provider "azurerm" { + features {} + + client_id = var.client_id + client_certificate_path = "/home/coder/az/client.pfx" + client_certificate_password = var.client_cert_password + tenant_id = var.tenant_id + subscription_id = var.subscription_id +} +``` + +Setting the `variable` values as `sensitive` means only the template writer can +see the values, and will only be prompted to input such values upon running +`coder templates push`. 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" } ] } From a4c3973e94244401e3d51f1d2113bc8654f56a79 Mon Sep 17 00:00:00 2001 From: Eric Date: Fri, 26 Jan 2024 21:59:52 +0000 Subject: [PATCH 2/3] make: fmt --- docs/guides/azure-federation.md | 56 ++++++++++++++++++--------------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/docs/guides/azure-federation.md b/docs/guides/azure-federation.md index 2212da2614934..63da392c08c59 100644 --- a/docs/guides/azure-federation.md +++ b/docs/guides/azure-federation.md @@ -11,23 +11,23 @@ January 26, 2024 --- This guide will walkthrough how to authenticate Coder's Terraform runner 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 +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: +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 Terraform runner to authenticate -the AzureRM provider: +Next, generate a `.pfx` file to be used by Coder's Terraform runner to +authenticate the AzureRM provider: ```console openssl pkcs12 -export -password pass:"Pa55w0rd123" -out client.pfx -inkey client.key -in client.crt @@ -35,39 +35,43 @@ openssl pkcs12 -export -password pass:"Pa55w0rd123" -out client.pfx -inkey clien ## 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: +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)" +- **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. +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. +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**. +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 +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. +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: From 9e41389ceff71e0344495214356c4807e5ba5815 Mon Sep 17 00:00:00 2001 From: Eric Date: Sun, 28 Jan 2024 20:16:59 +0000 Subject: [PATCH 3/3] refactor: arm secrets and semantics --- docs/guides/azure-federation.md | 81 +++++++++++++++------------------ 1 file changed, 37 insertions(+), 44 deletions(-) diff --git a/docs/guides/azure-federation.md b/docs/guides/azure-federation.md index 63da392c08c59..325991e9f4359 100644 --- a/docs/guides/azure-federation.md +++ b/docs/guides/azure-federation.md @@ -10,10 +10,10 @@ January 26, 2024 --- -This guide will walkthrough how to authenticate Coder's Terraform runner 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 +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 @@ -26,8 +26,8 @@ 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 Terraform runner to -authenticate the AzureRM provider: +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 @@ -79,10 +79,41 @@ Run the below command to create the secret: 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: @@ -98,41 +129,3 @@ Upgrade the Coder deployment using the following `helm` command: ```console helm upgrade coder coder-v2/coder -n coder -f values.yaml ``` - -## Step 5: Configure your Template to use the Client Certificate - -Now that the client certificate is added to Coder, it can be used by Terraform -to authenticate to Azure. Set the below arguments in your AzureRM provider block -in the workspace template: - -```hcl -variable "client_id" { - sensitive = true -} -variable "tenant_id" { - sensitive = true -} -variable "subscription_id" { - sensitive = true -} -variable "client_cert_path" { - sensitive = true -} -variable "client_cert_password" { - sensitive = true -} - -provider "azurerm" { - features {} - - client_id = var.client_id - client_certificate_path = "/home/coder/az/client.pfx" - client_certificate_password = var.client_cert_password - tenant_id = var.tenant_id - subscription_id = var.subscription_id -} -``` - -Setting the `variable` values as `sensitive` means only the template writer can -see the values, and will only be prompted to input such values upon running -`coder templates push`.