coder · deansheather · Nov 17, 2021 · Nov 10, 2021 · Nov 10, 2021 · Nov 15, 2021
diff --git a/admin/organizations/index.md b/admin/organizations/index.md
@@ -41,8 +41,8 @@ namespaces.
 
 If you want to separate Coder workspaces by namespaces in a Kubernetes cluster,
 you can do so by
-[deploying a new workspace provider](../workspace-providers/deployment.md) to
-each additional namespace in the cluster. The workspace provider provisions
+[deploying a new workspace provider](../workspace-providers/deployment/index.md)
+to each additional namespace in the cluster. The workspace provider provisions
 workspaces to the namespace it has been deployed to, and you can control access
 to each workspace provider via an organization allowlist to replace the previous
 organization namespace behaviors.
diff --git a/admin/registries/ecr.md b/admin/registries/ecr.md
@@ -6,41 +6,131 @@ description: Add a private Amazon ECR to Coder.
 This article will show you how to add your private ECR to Coder. If you're using
 a public ECR registry, you do not need to follow the steps below.
 
-Amazon requires users to [request temporary login credentials to access a
-private Elastic Container Registry (ECR)
-registry](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html).
-When interacting with ECR, Coder will request temporary credentials from the
-registry using the AWS credentials linked to the registry.
+Amazon requires users to
+[request temporary login credentials](https://docs.aws.amazon.com/AmazonECR/latest/userguide/registry_auth.html)
+to access a private Elastic Container Registry (ECR) registry. When interacting
+with ECR, Coder will request temporary credentials from the registry using the
+AWS credentials linked to the registry.
 
-## Step 1: Setting up your AWS credentials
+## Step 1: Setting up authentication for Coder
 
-To access a private ECR registry, Coder needs AWS credentials (specifically your
-**access key ID** and **secret access key**) with authorization to access the
-provided registry. You can either use AWS credentials tied to your own AWS
-account *or* credentials tied to an IAM user specifically for Coder (we
-recommend the latter option).
+To access a private ECR registry, Coder needs to authenticate with AWS. Coder
+supports two methods of authentication with AWS ECR:
 
-Note that you are not limited to providing one single set of AWS credentials.
-For example, you can use a set of credentials with access to all of your ECR
-repositories, or you can use individual sets of credentials, each with access to
-a single repository.
+- Static credentials
+- **Alpha:** IAM roles for service accounts
 
-To provision AWS credentials for Coder:
+### Option A: Provision static credentials for Coder
 
-1. **Optional:** [Create an IAM user for
-   Coder](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)
+You can use an **Access Key ID** and **Secret Access Key** tied to either your
+own AWS account _or_ credentials tied to a dedicated IAM user (we recommend the
+latter option).
+
+> You are not limited to providing a single set of AWS credentials. For example,
+> you can use a set of credentials with access to all of your ECR repositories,
+> or you can use individual sets of credentials, each with access to a single
+> repository.
+
+To provision static credentials for Coder:
+
+1. **Optional:**
+   [Create an IAM user for Coder](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html)
    to access ECR. You can either attach the AWS-managed policy
-   `AmazonEC2ContainerRegistryReadOnly` to the user, or you can [create your
-   own](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policy-examples.html).
+   `AmazonEC2ContainerRegistryReadOnly` to the user, or you can
+   [create your own](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-policy-examples.html).
 
-1. [Create an access
-   key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
+1. [Create an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html)
    for the IAM user to be used with Coder (if one does not already exist).
 
+### Option B: Link an AWS IAM role to the Coder Kubernetes service account (IRSA)
+
+**Note:** This is currently an **alpha** feature.
+
+Coder can use an
+[IAM role linked to Coder's Kubernetes service account](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/),
+though this is only supported when Coder is running in AWS EKS. This is because
+the
+[EKS Pod Identity Webhook](https://github.com/aws/amazon-eks-pod-identity-webhook/)
+is required to provision and inject the required token into the `coderd` pod.
+
+> For more information on IAM Roles for Service Accounts (IRSA), please consult
+> the
+> [AWS Documentation](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html).
+
+To link an IAM role to Coder's Kubernetes service account:
+
+1. Enable the feature under Manage > Admin > Infrastructure > ECR IAM Role
+   Authentication.
+
+1. Create an IAM OIDC Provider for your EKS cluster (if it does not already
+   exist).
+
+1. [Create the IAM role](https://docs.aws.amazon.com/eks/latest/userguide/create-service-account-iam-policy-and-role.html#create-service-account-iam-role)
+   to be used by Coder, if it does not already exist.
+
+   **Note:** Ensure that you also create and attach a trust policy that permits
+   the Coder service account the action `sts:AssumeRoleWithWebIdentity`. The
+   trust policy will look similar to the following:
+
+   ```json
+   {
+     "Version": "2012-10-17",
+     "Statement": [
+       {
+         "Effect": "Allow",
+         "Principal": {
+           "Federated": "arn:aws:iam::${ACCT_ID}:oidc-provider/${OIDC_PROVIDER}"
+         },
+         "Action": "sts:AssumeRoleWithWebIdentity",
+         "Condition": {
+           "StringEquals": {
+             "${OIDC_PROVIDER}:sub": "system:serviceaccount:${NAMESPACE}:${SERVICE_ACCOUNT}"
+           }
+         }
+       }
+     ]
+   }
+   ```
+
+1. Annotate the Coder service account with the role ARN:
+
+   a) Add the following to your `values.yaml` for your Coder helm deployment:
+
+   ```yaml
+   coderd:
+    ...
+    builtinProviderServiceAccount:
+      ...
+      annotations:
+        eks.amazonaws.com/role-arn: my-role-arn
+   ```
+
+   b) Update the Helm deployment:
+
+   ```shell
+   helm upgrade coder coder/coder --values values.yaml
+   ```
+
+   c) Verify that the Coder service account now has the correct annotation:
+
+   ```shell
+   kubectl get serviceaccount coder -o yaml | grep eks.amazonaws.com/role-arn
+     eks.amazonaws.com/role-arn: my-role-arn
+   ```
+
+1. Validate that pods created with the `coder` service account have permission
+   to assume the role:
+
+```shell
+kubectl run -it --rm awscli --image=amazon/aws-cli \
+  --overrides='{"spec":{"serviceAccount":"coder"}}' \
+  --command aws ecr describe-repositories
+```
+
 ## Step 2: Add your private ECR registry to Coder
 
-You can add your private ECR registry at the same time that you [add your
-images](../../images/index.md). To import an image:
+You can add your private ECR registry at the same time that you
+[add your images](../../images/index.md). To import an image:
 
 1. In Coder, go to **Images** and click on **Import Image** in the upper-right.
 
@@ -51,7 +141,9 @@ images](../../images/index.md). To import an image:
 1. Provide a **registry name** and the **registry**.
 
 1. Set the **registry kind** to **ECR** and provide your **Access Key ID** and
-   **Secret Access Key**.
+   **Secret Access Key**, if required. If you want to use IRSA instead of static
+   credentials, to authenticate with ECR, leave **Access Key ID** and **Secret
+   Access Key** blank.
 
 1. Continue with the process of [adding your image](../../images/index.md).
 

diff --git a/admin/workspace-management/self-contained-builds.md b/admin/workspace-management/self-contained-builds.md
@@ -0,0 +1,27 @@
+---
+title: "Self-contained workspace builds"
+description: Learn how to enable self-contained workspace builds.
+state: alpha
+---
+
+By default the Coder workspace boot sequence occurs remotely -- Coder uploads
+assets (including the Coder agent, code-server, and JetBrains Projector) from
+`coderd` to a workspace.
+
+However, Coder offers the option of using **self-contained workspace builds**.
+Enabling this option changes the Coder deployment so that workspaces control the
+boot sequence internally, with the workspace downloading assets from `coderd`.
+
+> At this time, Coder does not support certificate injectioin with
+> self-contained workspace builds.
+
+To enable self-contained workspace builds:
+
+1. Log into Coder.
+1. Go to Manage > Admin.
+1. On the Infrastructure page, scroll down to **Workspace container runtime**.
+1. Under **Enable self-contained workspace builds**, flip the toggle to **On**.
+1. Click **Save workspaces**.
+
+> Build errors are typically more verbose for remote builds than with
+> self-contained builds.
diff --git a/admin/workspace-providers/deployment/ec2.md b/admin/workspace-providers/deployment/ec2.md
@@ -0,0 +1,144 @@
+---
+title: EC2
+description: Learn how to deploy a workspace provider to an EC2 cluster.
+state: alpha
+---
+
+This article walks you through the process of deploying a workspace provider to
+an EC2 instance.
+
+The use of EC2 providers is currently an **alpha** feature. Before using, please
+enable this feature under **Feature Preview**:
+
+1. Log into Coder as a site manager or site admin.
+1. In the top-right, click on your avatar and select **Feature Preview**.
+1. Select **Amazon EC2 (Docker) providers** and click **Enable**.
+
+## Prerequisites
+
+You must have an
+[**AWS access key ID** and **secret access key**](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
+
+We recommend having the [AWS CLI](https://aws.amazon.com/cli/) installed and
+configured as well.
+
+### IAM permissions
+
+To manage EC2 providers for your Coder deployment, create an IAM policy and
+attach it to the IAM identity (e.g., role) that will be managing your resources
+(be sure to update or remove `aws:RequestedRegion` accordingly):
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Deny",
+      "Action": "ec2:*",
+      "Resource": "*",
+      "Condition": {
+        "StringNotEquals": {
+          "aws:RequestedRegion": "us-east-1"
+        }
+      }
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "ec2:DescribeAccountAttributes",
+        "ec2:DescribeSubnets",
+        "ec2:CreateSecurityGroup",
+        "ec2:DescribeSecurityGroups",
+        "ec2:AuthorizeSecurityGroupIngress",
+        "ec2:DeleteSecurityGroup",
+        "ec2:ImportKeyPair",
+        "ec2:DescribeKeyPairs",
+        "ec2:CreateVolume",
+        "ec2:DescribeVolumes",
+        "ec2:AttachVolume",
+        "ec2:DeleteVolume",
+        "ec2:RunInstances",
+        "ec2:DescribeInstances",
+        "ec2:DescribeInstanceStatus",
+        "ec2:TerminateInstances",
+        "ec2:DescribeInstanceTypes",
+        "ec2:CreateTags"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+## 1. Select the workspace provider type to create
+
+1. Log into Coder as a site manager, and go to **Manage** > **Workspace
+   providers**.
+
+1. In the top-right next to **Create Kubernetes Provider**, click on the **down
+   arrow** and select **Create Amazon EC2 Provider**.
+
+1. Provide a **name** to identify the provider.
+
+## 2. Configure the connection to AWS
+
+Provide the requested configuration details to connect Coder to your AWS
+account:
+
+- **Access key ID**: the AWS access key associated with your account
+- **Secret access key**: the AWS secret access key associated with your account
+- **AWS region ID**: select the AWS region where the EC2 instances should be
+  created
+- **AWS availability zone**: the AWS availability zone associated with the
+  region where the EC2 instances are created
+
+## 3. Provide networking information (optional)
+
+Provide the following networking options if desired:
+
+- VPC ID: Optional. The VPC network to which instances should be attached. If
+  you leave this field empty, Coder uses the default VPC ID in the specified
+  region for your EC2 instances
+- Subnet ID: Optional. The
+  [ID of the subnet](https://docs.aws.amazon.com/managedservices/latest/userguide/find-subnet.html)
+  associated with your VPC and availability zone. If you leave this field empty,
+  Coder uses the default subnet associated with the VPC in your region and
+  availability zone.
+
+## 4. Provide AMI configuration information
+
+Specify the Amazon Machine Image configuration you want to be used when
+launching workspaces:
+
+- **Privileged mode**: Optional. check this box if you would like the workspace
+  container to have read/write access to the EC2 instance's host filesystem
+
+> Privileged mode may pose a security risk to your organization. We recommend
+> enabling this feature only if users need full access to the host (e.g., kernel
+> driver development or running Docker-in-Docker).
+
+- **AMI ID**: the Amazon machine image ID to be used when creating the EC2
+  instances; the machine image used must contain and start a Docker daemon. If
+  blank, Coder defaults to an image that meets the requirements. If you selected
+  a supported AWS region, this will auto-populate with a supported AMI (though
+  you are welcome to change it)
+- **Instance types**: Optional. The EC2 instance types that users can provision
+  using the workspace provider. Provide each instance type on a separate line;
+  wildcard characters are allowed
+- **AMI SSH username**: the SSH login username used by Coder to connect to EC2
+  instances. Must be set if you provide a custom AMI ID (this value may be
+  auto-populated depending on the AMI you choose))
+- **Root volume size**: the storage capacity to be reserved for the copy of the
+  AMI
+- **Docker volume size**: the storage capacity used for the Docker daemon
+  directory; stores the workspace image and any ephemeral data outside of the
+  home directory
+
+## 5. Enable external connections (optional)
+
+Toggle **external connect** on if you would like to enable SSH connections to
+your workspaces via the Coder CLI.
+
+## 6. Create the provider
+
+Click **Create provider** to proceed.
diff --git a/admin/workspace-providers/deployment/index.md b/admin/workspace-providers/deployment/index.md
@@ -0,0 +1,6 @@
+---
+title: Deployment
+description: Learn how to deploy a workspace provider to a cluster.
+---
+
+<children></children>
diff --git a/admin/workspace-providers/deployment.md → ...kspace-providers/deployment/kubernetes.md b/admin/workspace-providers/deployment.md → ...kspace-providers/deployment/kubernetes.md
@@ -1,12 +1,12 @@
 ---
-title: Workspace provider deployment
-description: Learn how to deploy a workspace provider.
+title: Kubernetes
+description: Learn how to deploy a workspace provider to a Kubernetes cluster.
 ---
 
 This article walks you through the process of deploying a workspace provider to
 a Kubernetes cluster. If you do not have one, you can use our
-[cluster guides](../../setup/kubernetes/index.md) to create one compatible with
-Coder.
+[cluster guides](../../../setup/kubernetes/index.md) to create one compatible
+with Coder.
 
 ## Dependencies
 
@@ -56,7 +56,7 @@ Install the following dependencies if you haven't already:
      name: coder
    rules:
      - apiGroups: ["", "apps", "networking.k8s.io"] # "" indicates the core API group
-       resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies"]
+       resources: ["persistentvolumeclaims", "pods", "deployments", "services", "secrets", "pods/exec","pods/log", "events", "networkpolicies", "serviceaccounts"]
        verbs: ["create", "get", "list", "watch", "update", "patch", "delete", "deletecollection"]
      - apiGroups: ["metrics.k8s.io", "storage.k8s.io"]
        resources: ["pods", "storageclasses"]

diff --git a/admin/workspace-providers/index.md b/admin/workspace-providers/index.md
@@ -30,8 +30,8 @@ create workspaces.
 
 Remote workspace providers can lower developers' latency by locating their
 workspaces closer to them geographically or can be used for workload isolation
-purposes. See [Deploying a workspace provider](deployment.md) to learn how to
-expand your Coder deployment to additional Kubernetes clusters.
+purposes. See [Deploying a workspace provider](deployment/index.md) to learn how
+to expand your Coder deployment to additional Kubernetes clusters.
 
 ### Organization allowlists