Add AWS ECR support (round two)

binderhub/app.py

@@ -20,7 +20,7 @@
 import tornado.log
 from tornado.log import app_log
 import tornado.web
-from traitlets import Unicode, Integer, Bool, Dict, validate, TraitError, Union, default
+from traitlets import Unicode, Integer, Bool, Dict, validate, TraitError, Union, default, Type
 from traitlets.config import Application
 from jupyterhub.services.auth import HubOAuthCallbackHandler
 from jupyterhub.traitlets import Callable
@@ -207,6 +207,15 @@ def _valid_badge_base_url(self, proposal):
         config=True,
     )
 
+    docker_registry_class = Type(
+        DockerRegistry,
+        help="""
+        Change this to support different Docker container registries.
+        The default works with GCR, ACR and DockerHub. Use `AWSElasticContainerRegistry` for AWS ECR.
+        """,
+        config=True
+    )
+
     sticky_builds = Bool(
         False,
         help="""
@@ -569,7 +578,7 @@ def initialize(self, *args, **kwargs):
         ])
         jinja_env = Environment(loader=loader, **jinja_options)
         if self.use_registry and self.builder_required:
-            registry = DockerRegistry(parent=self)
+            registry = self.docker_registry_class(parent=self)
         else:
             registry = None
 

binderhub/registry.py

@@ -1,15 +1,20 @@
 """
 Interaction with the Docker Registry
 """
+import asyncio
 import base64
+from concurrent.futures import ThreadPoolExecutor
 import json
 import os
 from urllib.parse import urlparse
 
+import boto3
+import kubernetes.client
+import kubernetes.config
 from tornado import gen, httpclient
 from tornado.httputil import url_concat
+from traitlets import default, Dict, Unicode, Any, Integer
 from traitlets.config import LoggingConfigurable
-from traitlets import Dict, Unicode, default
 
 DEFAULT_DOCKER_REGISTRY_URL = "https://registry.hub.docker.com"
 DEFAULT_DOCKER_AUTH_URL = "https://index.docker.io/v1"
@@ -224,3 +229,81 @@ def get_image_manifest(self, image, tag):
                 raise
         else:
             return json.loads(resp.body.decode("utf-8"))
+
+
+class AWSElasticContainerRegistry(DockerRegistry):
+    aws_region = Unicode(
+        config=True,
+        help="""
+        AWS region for ECR service
+        """,
+    )
+
+    ecr_client = Any()
+
+    @default("ecr_client")
+    def _get_ecr_client(self):
+        return boto3.client("ecr", region_name=self.aws_region)
+
+    username = "AWS"
+
+    executor_threads = Integer(
+        5,
+        config=True,
+        help="""The number of threads to use for blocking calls
+
+        Should generaly be a small number because we don't
+        care about high concurrency here, just not blocking the webserver.
+        This executor is not used for long-running tasks (e.g. builds).
+        """,
+    )
+
+    executor = Any()
+
+    @default("executor")
+    def _get_executor(self):
+        return ThreadPoolExecutor(self.executor_threads)
+
+    kube_client = Any()
+
+    @default("kube_client")
+    def _get_kube_client(self):
+        kubernetes.config.load_incluster_config()
+        return kubernetes.client.CoreV1Api()
+
+    async def get_image_manifest(self, image, tag):
+        image = image.split("/", 1)[1]
+        await asyncio.wrap_future(self.executor.submit(self._pre_get_image_manifest, image, tag))
+        return await super().get_image_manifest(image, tag)
+
+    def _pre_get_image_manifest(self, image, tag):
+        self._create_repository(image, tag)
+        self._refresh_password()
+
+    def _create_repository(self, image, tag):
+        try:
+            self.ecr_client.create_repository(repositoryName=image)
+            self.log.info("ECR repo {} created".format(image))
+        except self.ecr_client.exceptions.RepositoryAlreadyExistsException:
+            self.log.info("ECR repo {} already exists".format(image))
+
+    # An IAM principal is used to generate an auth token that is valid for 12 hours
+    # ref: https://docs.aws.amazon.com/AmazonECR/latest/userguide/Registries.html
+    # TODO: cache auth if not expired - authorizationData[i]["expiresAt"]
+    def _refresh_password(self):
+        auths = self.ecr_client.get_authorization_token()["authorizationData"]
+        auth = next(x for x in auths if x["proxyEndpoint"] == self.url)
+        self._patch_docker_config_secret(auth)
+        self.password = base64.b64decode(auth['authorizationToken']).decode("utf-8").split(':')[1]
+
+    def _patch_docker_config_secret(self, auth):
+        """Patch binder-push-secret"""
+        secret_data = {"auths": {self.url: {"auth": auth["authorizationToken"]}}}
+        secret_data = base64.b64encode(json.dumps(secret_data).encode("utf8")).decode(
+            "utf8"
+        )
+        with open("/var/run/secrets/kubernetes.io/serviceaccount/namespace") as f:
+            namespace = f.read()
+        self.kube_client.patch_namespaced_secret(
+            "binder-push-secret", namespace, {"data": {"config.json": secret_data}}
+        )

doc/doc-requirements.txt

@@ -20,3 +20,4 @@ jupyterhub
 jsonschema
 tornado>=5.1
 #pycurl Do not install for docs as it breaks the RTD build. Its primary use is for mocks in testing .
+boto3

doc/zero-to-binderhub/setup-binderhub.rst

@@ -118,7 +118,6 @@ where:
 
 If you are using OVH Container Registry
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Update `secret.yaml` to include the following::
 
     registry:
@@ -133,6 +132,22 @@ where:
 * `<harbor-username>` is the Harbor username
 * `<harbor-password>` is the Harbor password
 
+If you are using Amazon Elastic Container Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Update `secret.yaml` to include the following::
+
+    registry:
+      url: https://<ACCOUNT_NUMBER>.dkr.ecr.<REGION>.amazonaws.com
+
+where:
+
+* ``<ACCOUNT_NUMBER>`` is the identifier of your AWS account
+* ``<REGION>`` is the AWS region of the ECR registry, e.g. ``us-east-1``
+
+As ECR uses AWS IAM for authorization, specifying ``username`` and ``password``
+is not necessary.
+
 Create ``config.yaml``
 ----------------------
 
@@ -230,6 +245,37 @@ As an example, the config should look like the following::
         url: https://abcde.gra7.container-registry.ovh.net
         token_url: https://abcde.gra7.container-registry.ovh.net/service/token?service=harbor-registry
 
+If you are using Amazon Elastic Container Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want your BinderHub to push and pull images from an Amazon Elastic
+Container Registry (ECR), then your `config.yaml` file will look as follows::
+
+    config:
+      BinderHub:
+        use_registry: true
+        docker_registry_class: binderhub.registry.AWSElasticContainerRegistry
+        image_prefix: "<ACCOUNT_NUMBER>.dkr.ecr.<REGION>.amazonaws.com/<prefix>-"
+      AWSElasticContainerRegistry:
+        aws_region: <REGION>
+
+where:
+
+* ``<ACCOUNT_NUMBER>`` is the identifier of your AWS account
+* ``<REGION>`` is the AWS region of the ECR registry, e.g. ``us-east-1``.
+* ``<prefix>`` can be any string, and will be prepended to image names. We
+  recommend something descriptive such as ``binder-dev-`` or ``binder-prod-``
+  (ending with a `-` is useful).
+
+If you opted to use an IAM User with programmatic access instead of assuming
+the role in the previous step you will additionally need to add the following
+to your `config.yaml`::
+
+    extraEnv:
+    - name: AWS_ACCESS_KEY_ID
+      value: "xxx"
+    - name: AWS_SECRET_ACCESS_KEY
+      value: "yyy"
 
 If you are using a custom registry
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/zero-to-binderhub/setup-registry.rst

@@ -167,6 +167,99 @@ To use the OVH Container Registry, log in to the `OVH Control Panel <https://www
 
 For more information about these steps, check out the `OVH Documentation <https://docs.ovh.com/gb/en/private-registry/creating-a-private-registry>`_
 
+.. _use-ecr:
+
+Set up Amazon Elastic Container Registry
+----------------------------------------
+
+To use Amazon Elastic Container Registry (ECR), you'll need to use AWS IAM to
+authorize the machine or pod running BinderHub so it can push images. There
+are a number of options on how to do this with IAM and Kubernetes, but we
+will highlight two: define and assign an IAM role, or assume an IAM user with programmatic access.
+
+For the former, start by creating an IAM policy that grants access to create repositories and
+read/write images from them. You can create policies using the AWS console, CLI 
+or API as detailed in the documentation `Creating IAM policies <https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html>`_. 
+An example IAM permissions policy is provided below. For more information and examples see `Identity and Access Management for Amazon Elastic Container Registry <https://docs.aws.amazon.com/AmazonECR/latest/userguide/security-iam.html>`_.
+
+.. code-block:: json
+
+        {
+            "Statement": [
+                {
+                    "Action": [
+                        "ecr:ListImages"
+                    ],
+                    "Effect": "Allow",
+                    "Resource": "arn:aws:ecr:<REGION>:<ACCOUNT_NUMBER>:<prefix>-*",
+                    "Sid": "ListImagesInRepository"
+                },
+                {
+                    "Action": [
+                        "ecr:GetAuthorizationToken"
+                    ],
+                    "Effect": "Allow",
+                    "Resource": "*",
+                    "Sid": "GetAuthorizationToken"
+                },
+                {
+                    "Action": [
+                        "ecr:BatchCheckLayerAvailability",
+                        "ecr:GetDownloadUrlForLayer",
+                        "ecr:GetRepositoryPolicy",
+                        "ecr:DescribeRepositories",
+                        "ecr:ListImages",
+                        "ecr:DescribeImages",
+                        "ecr:BatchGetImage",
+                        "ecr:InitiateLayerUpload",
+                        "ecr:UploadLayerPart",
+                        "ecr:CompleteLayerUpload",
+                        "ecr:PutImage"
+                    ],
+                    "Effect": "Allow",
+                    "Resource": "arn:aws:ecr:<REGION>:<ACCOUNT_NUMBER>:<prefix>-*",
+                    "Sid": "ManageRepositoryContents"
+                },
+                {
+                    "Action": [
+                        "ecr:CreateRepository"
+                    ],
+                    "Effect": "Allow",
+                    "Resource": "arn:aws:ecr:<REGION>:<ACCOUNT_NUMBER>:<prefix>-*",
+                    "Sid": "CreateRepository"
+                }
+            ],
+            "Version": "2012-10-17"
+        }
+
+If you used AWS services like EC2 or EKS to set up your Kubernetes cluster you
+can add this policy to the IAM Role assumed by the nodes of the cluster, e.g.
+``nodes.<somename>.k8s.local`` if you followed `Zero to JupyterHub with Kubernetes <https://zero-to-jupyterhub.readthedocs.io/>`_
+and used kops. One way to do this from the AWS Console is to navigate to the IAM service and click "Roles" in the side bar, 
+then find and select the IAM Role assumed by the nodes of your cluster, click "Permissions" and then "Attach policies" to attach 
+the IAM Policy we just created. The IAM permissions policy will need to accompanied with an IAM
+trust policy to allow it to be assumed. A suitable trust policy may already be defined for your node's IAM Role, 
+you can view and edit the trust policy by clicking the "Trust relationships" tab is next to the "Permissions" tab in the AWS console. 
+An example trust policy for EC2 is provided below. For more information see `Granting a User Permissions to Pass a Role to an AWS Service <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html>`_.
+This is the recommended method if your Kubernetes cluster is provisioned on AWS.
+
+.. code-block:: json
+
+        {
+            "Version": "2012-10-17",
+            "Statement": {
+                "Sid": "TrustPolicyStatementThatAllowsEC2ServiceToAssumeTheAttachedRole",
+                "Effect": "Allow",
+                "Principal": { "Service": "ec2.amazonaws.com" },
+            "Action": "sts:AssumeRole"
+            }
+        }
+
+Alternatively to the above steps, you can create an IAM user with programmatic access (see
+`Creating an IAM User in Your AWS Account <https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html>`_)
+and specify the ``AWS_ACCESS_KEY_ID`` and ``AWS_SECRET_ACCESS_KEY`` environment
+variables in the following step.
+
 Next step
 ---------
 

helm-chart/binderhub/templates/rbac.yaml

@@ -14,6 +14,9 @@ rules:
 - apiGroups: [""]
   resources: ["pods/log"]
   verbs: ["get"]
+- apiGroups: [""]
+  resources: ["secrets"]
+  verbs: ["get", "patch"]
 ---
 kind: RoleBinding
 apiVersion: rbac.authorization.k8s.io/v1beta1

requirements.txt

@@ -11,4 +11,4 @@ jupyterhub
 jsonschema
 pycurl
 tornado>=5.1
-
+boto3