BinderHub Container Registry Helper

A microservice to help BinderHub work with Public cloud container registries.

Some cloud registries require a repository to be created before it can be used. This micro-service provides a simple REST API to create repositories on demand, avoiding the need to integrate cloud provider libraries into BinderHub.

The following cloud provider registries are supported:

• Oracle Cloud Infrastructure container registry
• Amazon Web Services Elastic Container Registry (Amazon ECR)

Build and run locally

You must install Go 1.18. If you are a Python developer using Conda or Mamba and just want a quick way to install Go:

conda create -n go -c conda-forge go=1.18 go-cgo=1.18
conda activate go

make build
make test

Run with Oracle Cloud Infrastructure using a local OCI configuration file oci-config and private key oci_api_key.pem:

BINDERHUB_AUTH_TOKEN=secret-token ./binderhub-oracle oci-config

Run with Amazon Web Services using the local AWS credentials:

BINDERHUB_AUTH_TOKEN=secret-token ./binderhub-amazon

API endpoints

List repositories

curl -H'Authorization: Bearer secret-token' localhost:8080/repos/

Create repository foo/test (ignores repositories that already exist)

curl -XPOST -H'Authorization: Bearer secret-token' localhost:8080/repo/foo/test

Get repository foo/test

curl -H'Authorization: Bearer secret-token' localhost:8080/repo/foo/test

Delete repository foo/test (ignores repositories that don't exist)

curl -XDELETE -H'Authorization: Bearer secret-token' localhost:8080/repo/foo/test

Get credentials for repository foo/test (only for Amazon, returns 404 for Oracle)

curl -XPOST -H'Authorization: Bearer secret-token' localhost:8080/token/foo/test

Build and run container

podman build -t binderhub-container-registry-helper .

Oracle Cloud Infrastructure:

podman run --rm -it \
  -eBINDERHUB_AUTH_TOKEN=secret-token \
  -eOCI_COMPARTMENT_ID=oci.compartment.id \
  -v ./oci-config:/oci-config:ro,z \
  -v ./oci_api_key.pem:/oci_api_key.pem:ro,z \
  -p8080:8080 \
  binderhub-container-registry-helper binderhub-oracle /oci-config

Amazon Web Services:

podman run --rm -it \
  -eBINDERHUB_AUTH_TOKEN=secret-token \
  -eAWS_REGION=region \
  -eAWS_ACCESS_KEY_ID=access-key \
  -eAWS_SECRET_ACCESS_KEY=seret-key \
  -eRETURN_ERROR_DETAILS=1 \
  -p8080:8080 \
  binderhub-container-registry-helper binderhub-amazon

Running in the cloud

The recommended way to run this service is to use an IAM instance principal (Oracle Cloud) or instance profile (AWS) to authenticate with the cloud provider.

Environment variables

The following environment variables are supported:

• BINDERHUB_AUTH_TOKEN: Secret token used to authenticate callers who should set the Authorization: Bearer {BINDERHUB_AUTH_TOKEN} header. Set BINDERHUB_AUTH_TOKEN="" to disable authentication.
• RETURN_ERROR_DETAILS: If set to 1 internal error details will be returned in the response body to clients. This may include internal configuration information, only enable this for internal use. Default 0.

Amazon only:

• AWS_REGISTRY_ID: Registry ID to use for AWS ECR, only set this is you are not using the default registry for the AWS account.

Oracle cloud infrastructure only:

• OCI_COMPARTMENT_ID: OCI compartment or tenancy OCID if not the default.

BinderHub example (Helm chart)

This repository includes an OCI Helm chart to deploy this service to a Kubernetes cluster. Deploy the OCI Helm chart, see Values.yaml for configuration options.

helm repo add binderhub-container-registry-helper https://www.manicstreetpreacher.co.uk/binderhub-container-registry-helper/

helm upgrade binderhub-container-registry-helper/binderhub-container-registry-helper --version <VERSION>

Append this example BinderHub configuration to your BinderHub extraConfig section. For example:

extraConfig:
  10-external-registry-helper: |
    <binderhub-example/binderhub_config.py>

Development

Build and run

make build
make test

For more detailed testing of a single module or test:

go test -v ./common/
go test -v ./common -run TestGetName

Add a new module

go mod tidy

Debug logging

The Oracle Cloud SDK supports the environment variable OCI_GO_SDK_DEBUG={info,debug,verbose}. Unfortunately the AWS SDK does not have an equivalent.