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,14 @@ def _valid_badge_base_url(self, proposal):
         config=True,
     )
 
+    registry_class = Type(
+        DockerRegistry,
+        help="""
+        Registry class implementation, change to define your own
+        """,
+        config=True
+    )
+
     sticky_builds = Bool(
         False,
         help="""
@@ -554,7 +562,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.registry_class(parent=self)
         else:
             registry = None
 

binderhub/registry.py

@@ -6,10 +6,13 @@
 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
 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 +227,61 @@ 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)
+
+    # TODO: cache auth if not expired - authorizationData[i]["expiresAt"]
+    def _get_ecr_auth(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)
+        return auth
+
+    username = "AWS"
+
+    @property
+    def password(self):
+        # Fetch password every time as ECR password expires
+        auth = self._get_ecr_auth()
+        return base64.b64decode(auth['authorizationToken']).decode("utf-8").split(':')[1]
+
+    async def get_image_manifest(self, image, tag):
+        try:
+            repo_name = image.split("/", 1)[1]
+            self.ecr_client.create_repository(repositoryName=repo_name)
+            self.log.info("ECR repo {} created".format(repo_name))
+        except self.ecr_client.exceptions.RepositoryAlreadyExistsException:
+            self.log.info("ECR repo {} already exists".format(repo_name))
+        return await super().get_image_manifest(repo_name, tag)
+
+    kube_client = Any()
+
+    @default("kube_client")
+    def _get_kube_client(self):
+        kubernetes.config.load_incluster_config()
+        return kubernetes.client.CoreV1Api()
+
+    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 @@ python-json-logger
 jupyterhub
 jsonschema
 #pycurl Do not install for docs as it breaks the RTD build. Its primary use is for mocks in testing .
+boto3

doc/setup-binderhub.rst

@@ -116,6 +116,22 @@ where:
 * `<SERVICE_PRINCIPAL_ID>` is the AppID of the Service Principal with AcrPush role assignment,
 * `<SERVICE_PRINCIPAL_PASSWORD>` is the password for the Service Principal.
 
+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``
 ----------------------
 
@@ -183,6 +199,38 @@ where:
   If this is not provided, you may find BinderHub rebuilds images every launch instead of pulling them from the ACR.
   Suggestions for `<project-name>` could be `ACR_NAME` or the name you give your BinderHub.
 
+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
+        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/setup-registry.rst

@@ -137,6 +137,96 @@ where:
        SERVICE_PRINCIPAL_PASSWORD=$(az ad sp create-for-rbac --name <SP_NAME> --role AcrPush --scopes <ACR_ID> --query password --output tsv)
        SERVICE_PRINCIPAL_ID=$(az ad sp show --id http://<SP_NAME> --query appId --output tsv)
 
+.. _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: assume IAM role and IAM user with programmatic access.
+
+Start by creating an IAM policy that grants access to create repositories and
+read/write images from them. 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. The IAM permissions policy will need to accompanied with an IAM
+trust policy to allow it to be assumed. An example 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, 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,3 +11,4 @@ python-json-logger
 jupyterhub
 jsonschema
 pycurl
+boto3