[MRG] Add instructions for setting up an Azure Container Registry

doc/setup-binderhub.rst

@@ -100,6 +100,21 @@ Update ``secret.yaml`` by entering the following::
    * ``<docker-id>`` and ``<password>`` are your credentials to login to Docker Hub.
      If you use an organization to store your Docker images, this account must be a member of it.
 
+If you are using Azure Container Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Update `secret.yaml` to include the following::
+
+    registry:
+      url: https://<ACR_NAME>.azurecr.io
+      username: <SERVICE_PRINCIPAL_ID>
+      password: <SERVICE_PRINCIPAL_PASSWORD>
+
+where:
+
+* `<ACR_NAME>` is the name you gave to your Azure Container Registry,
+* `<SERVICE_PRINCIPAL_ID>` is the AppID of the Service Principal with AcrPush role assignment,
+* `<SERVICE_PRINCIPAL_PASSWORD>` is the password for the Service Principal.
 
 Create ``config.yaml``
 ----------------------
@@ -148,6 +163,25 @@ Update ``config.yaml`` by entering the following::
      recommend something descriptive such as ``binder-dev-`` or ``binder-prod-``
      (ending with a `-` is useful).
 
+If you are using Azure Container Registry
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want your BinderHub to push and pull images from an Azure Container Registry (ACR), then your `config.yaml` file will look as follows::
+
+    config:
+      BinderHub:
+        use_registry: true
+        image_prefix: <ACR_NAME>.azurecr.io/<project-name>/<prefix>-
+      DockerRegistry:
+        token_url: "https://<ACR_NAME>.azurecr.io/oauth2/token?service=<ACR_NAME>.azurecr.io"
+
+where:
+
+* `<ACR_NAME>` is the name you gave to your ACR,
+* `<project-name>` is an arbitrary name that is required due to BinderHub assuming that the image_prefix contains an extra level for the project name.
+  See `this issue <https://github.com/jupyterhub/binderhub/issues/800>`_ for futher discussion.
+  If this is not provided, you may find BinderHub rebuilds images every launch instead of pulling them from the ACR.
+
 If you are using a custom registry
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -206,7 +240,14 @@ If you setup your own local registry using
     and can handle these without any additional configuration
     beyond `registry.url`.
 
+.. important::
+
+    BinderHub assumes that the image_prefix contains an extra level for the project name such that: `gcr.io/<project-id>/<prefix>-name:tag`.
+    Hence, your `image_prefix` field should be set to: `your-registry.io/<some-project-name>/<prefix>-`.
+    See `this issue <https://github.com/jupyterhub/binderhub/issues/800>`_ for more details.
 
+    `<some-project-name>` can be completely arbitrary and/or made-up.
+    Without this, you may find that your BinderHub always rebuilds images instead of pulling them from the registry.
 
 Install BinderHub
 -----------------

doc/setup-registry.rst

@@ -60,6 +60,88 @@ This is useful if different Binder instances want to use same registry to store
 See the next section for how to properly configure your BinderHub to use
 Docker Hub.
 
+.. _use-acr:
+
+Set up Azure Container Registry
+-------------------------------
+
+To use Azure Container Registry (ACR), you'll need to provide BinderHub with proper credentials so it can push images.
+You can do so by creating a `Service Principal <https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals>`_ that has the `AcrPush <https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#acrpush>`_ role.
+
+This section uses the Azure command line.
+Installation instructions can be found in the `Microsoft docs <https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest>`_.
+
+1. Login to your Azure account::
+
+       az login
+
+2. Select your chosen subscription::
+
+       az account set -s <SUBSCRIPTION>
+
+.. note::
+
+   You can see which subscriptions you have available by running::
+
+       az account list --refresh --output table
+
+3. If you **do not** have a Resource Group, then create one::
+
+       az group create --name <RESOURCE_GROUP_NAME> --location <RESOURCE_GROUP_LOCATION> --output table
+
+where `<RESOURCE_GROUP_LOCATION>` refers to a data centre **region**.
+See a list of regions `here <https://azure.microsoft.com/en-us/global-infrastructure/locations/>`_.
+
+If you already have a Resource Group you'd like to use, then you can skip this step.
+
+4. Create the ACR::
+
+       az acr create --name <ACR_NAME> --resource-group <RESOURCE_GROUP_NAME> --sku Basic --output table
+
+where:
+
+* `<ACR_NAME>` must be between 5-50 alphanumeric characters and is unique to Azure.
+  If you're not sure your chosen name is available, you can run `az acr check-name --name <ACR_NAME> --output table`.
+* `--sku` is the pricing and capacity tier for the registry.
+  See `this page <https://docs.microsoft.com/en-us/azure/container-registry/container-registry-skus>`_ for more details.
+
+5. Login in the ACR::
+
+       az acr login --name <ACR_NAME>
+
+6. Note down the AppID of the ACR::
+
+       az acr show --name <ACR_NAME> --query "id" -o tsv
+
+We need this in order to assign the AcrPush role which will allow BinderHub to push images to the registry.
+You can save this to a bash variable like so::
+
+    ACR_ID=$(az acr show --name <ACR_NAME> --query "id" -o tsv)
+
+7. Create a Service Principal with the AcrPush role assignment::
+
+       az ad sp create-for-rbac --name <SP_NAME> --role AcrPush --scope <ACR_ID>
+
+where:
+
+* `<SP_NAME>` is a recognisable name for your Service Principal, for example `binderhub-sp`,
+* `<ACR_ID>` is the AppID we retrieved in step 6 above.
+  You can replace this with `${ACR_ID}` if you saved it to a bash variable.
+
+.. important::
+
+   Note down the AppID and password that are output by this step.
+   These are the login credentials BinderHub will use to access the registry.
+
+   **The password will not be recoverable after this step, so make sure you keep it safe!**
+
+   If you'd like to save this info to bash variables, you can replace step 8 with the following commands::
+
+       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)
+
+See the next section for how to properly configure your BinderHub to use Azure Container Registry.
+
 Next step
 ---------