You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/howto/features/imagebuilding.md
+60-23Lines changed: 60 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -4,9 +4,9 @@ We can support users who want to build, push and launch user images, from open s
4
4
5
5
We call this an `imagebuilding` style hub and the primary features offered would be:
6
6
7
-
1.User authentication
8
-
2.Persistent storage
9
-
3.Server options allowing:
7
+
-**User authentication**
8
+
-**Persistent storage**
9
+
-**Server options** allowing:
10
10
- pre-defined list of images to choose from
11
11
- specifying another image, different from the ones in the pre-defined list
12
12
- building and pushing an image to a registry from a GitHub repository
@@ -69,27 +69,63 @@ jupyterhub:
69
69
image: jupyter/scipy-notebook:2023-06-26
70
70
```
71
71
72
-
## Setup the `binderhub-service` chart
72
+
## Setup the image registry
73
73
74
-
We will use the [binderhub-service](https://github.com/2i2c-org/binderhub-service/) Helm chart to run BinderHub, the Python software, as a standalone service to build and push images with [repo2docker](https://github.com/jupyterhub/repo2docker), next to JupyterHub.
74
+
### For GCP (via terraform)
75
+
76
+
If the hub will be deployed on a GCP cluster, we can setup [gcr.io](https://gcr.io) via the [terraform config](https://github.com/2i2c-org/infrastructure/blob/master/terraform/gcp/registry.tf).
77
+
78
+
1. Enable the repository creation by adding the following in the cluster's terraform config:
79
+
80
+
```terraform
81
+
container_repos = [
82
+
"some-other-repository",
83
+
"<repository-name>",
84
+
]
85
+
```
86
+
87
+
where <repository-name> is the name of the repository where all the images built from the hub will be pushed.
88
+
89
+
```{note}
90
+
If a `container_repos` config already exists, then, just add the new repository name to this list.
91
+
```
75
92
76
-
1. Setup a registry and safely store the credentials to push to it
93
+
2. Get the registry credentials
77
94
78
-
- If the hub will be deployed on a GCP cluster, follow the steps 4 to 8 from the [binderhub-service installation guide](https://github.com/2i2c-org/binderhub-service?tab=readme-ov-file#installation). When you're done, you should have a gcr.io registry setup and the appropriate credentials to push images to it.
95
+
The username to access this registry is [`_json_key`](https://cloud.google.com/artifact-registry/docs/docker/authentication#json-key) and the password can be discovered by running the following terraform command:
79
96
80
-
- If the hub will be deployed on another cloud provider than GCP, then you should setup the desired quay.io repository and robot account to push and pull from it. The steps below describes how to create one under the 2i2c quay.io organization, assuming this is where we wish the repositories that will be build by `binderhub-service` to be pushed.
97
+
```bash
98
+
terraform output registry_sa_keys
99
+
```
81
100
82
-
- Go to https://quay.io/organization/2i2c
83
-
- Select the 'Robot Accounts' option on the left menu.
84
-
- Click 'Create Robot account', give it a memorable name (such as `<cluster_name>_<hub-name>_image_builder`) and click 'Create'
85
-
- In the next screen, don't select any of the existing repositories, as we need this robot account to have enough permissions to push **any** new repository under the organization and permissions to existing repositories is not needed.
86
-
- Once done, click the name of the robot account again. This will give you its username and password.
87
-
- Select the 'Team and Membership' option on the left menu.
88
-
- Click on the 'Options' wheel of the `owners` team, then select 'Manage Team Members'
89
-
- Type in the name of the robot account that you created, select it from the list and add it to the `owners` team
101
+
```{important}
102
+
Store these somewhere safe as we will need them in a following step.
103
+
```
90
104
105
+
### For other cloud providers (quay.io)
91
106
92
-
2. Setup the `binderhub-service` config
107
+
If the hub will be deployed on another cloud provider than GCP, we must setup a new [quay.io](https://quay.io) organization and a robot account to push and pull from it.
108
+
109
+
1. Go to https://quay.io/organizations/new/ and create a new organization. Give it a memorable name like <cluster-name>-<hub-name>.
110
+
2. Make sure this new organization is selected, by going to https://quay.io/organization/<new-org-name>.
111
+
3. Select the 'Robot Accounts' option on the left menu.
112
+
3. Click 'Create Robot account', give it a memorable name (such as `image_builder`) and click 'Create'.
113
+
4. In the next screen, don't select any of the existing repositories, as we need this robot account to have enough permissions to push **any** new repository under the organization, so permissions to existing repositories is not needed.
114
+
5. Once done, click the name of the robot account again. This will give you its username and password.
115
+
```{important}
116
+
Store these somewhere safe as we will need them in a following step.
117
+
```
118
+
6. Select the 'Team and Membership' option on the left menu.
119
+
7. Click on the 'Options' wheel of the `owners` team, then select 'Manage Team Members'.
120
+
8. Type in the name of the robot account that you created, select it from the list and add it to the `owners` team.
121
+
9. Add also the other engineers as members of this new organization by searching their handles in the search bar on the right.
122
+
123
+
124
+
## Setup the `binderhub-service` chart
125
+
126
+
We will use the [binderhub-service](https://github.com/2i2c-org/binderhub-service/) Helm chart to run BinderHub, the Python software, as a standalone service to build and push images with [repo2docker](https://github.com/jupyterhub/repo2docker), next to JupyterHub.
127
+
128
+
1. Setup the `binderhub-service` config
93
129
94
130
```yaml
95
131
binderhub-service:
@@ -100,22 +136,23 @@ We will use the [binderhub-service](https://github.com/2i2c-org/binderhub-servic
100
136
# or quay.io/org/repo/cluster-hub/ for quay.io
101
137
image_prefix: <repository_path>
102
138
buildPodsRegistryCredentials:
103
-
# registry server address like https://quay.io
139
+
# registry server address like https://quay.io or https://us-central1-docker.pkg.dev
104
140
server: <server_address>
105
141
# robot account namer or "_json_key" if using grc.io
106
142
username: <account_name>
107
143
```
108
144
109
-
3. Sops-encrypt and store the password of the registry account, in the `enc-<hub>.secret.values.yaml` file.
145
+
2. Sops-encrypt and store the password for accessing the image registry, in the `enc-<hub>.secret.values.yaml` file.
146
+
147
+
You should have the password for accessing the image registry from a previous step.
110
148
111
149
```yaml
112
150
binderhub-service:
113
151
buildPodsRegistryCredentials:
114
-
password: |
115
-
<json_key_from_service_account>
152
+
password: <password>
116
153
```
117
154
118
-
4. If pushing to quay.io registry, also setup the credentials for image pulling
155
+
3. If pushing to quay.io registry, also setup the credentials for image pulling
119
156
120
157
When pushing to the quay registry, the images are pushed as `private` by default (even if the plan doesn't allow it).
121
158
@@ -127,5 +164,5 @@ We will use the [binderhub-service](https://github.com/2i2c-org/binderhub-servic
0 commit comments