Skip to content

Commit 3e65ee5

Browse files
roehrich-hperoehrich-hpe
authored
Using a private repository for user containers (#69)
Document the use of a private repository for a user's containerized application, and the use of ImagePullSecrets to let k8s access that container. Create a basic NNF User Container doc to create a place to land the above doc. Signed-off-by: Dean Roehrich <dean.roehrich@hpe.com>
1 parent 69eaaa0 commit 3e65ee5

3 files changed

Lines changed: 147 additions & 0 deletions

File tree

‎docs/guides/index.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,9 @@
1212

1313
* [Storage Profiles](storage-profiles/readme.md)
1414
* [Data Movement Configuration](data-movement/readme.md)
15+
16+
## NNF User Containers
17+
18+
* [User Containers](user-containers/readme.md)
19+
20+

‎docs/guides/user-containers/readme.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# NNF User Containers
2+
3+
NNF User Containers are a mechanism to allow user-defined containerized
4+
applications to be run on Rabbit nodes with access to NNF ephemeral and persistent storage.
5+
6+
!!! note
7+
8+
The following is a limited look at User Containers. More content will be
9+
provided after the RFC has been finalized.
10+
11+
## Custom NNFContainerProfile
12+
13+
The author of a containerized application will work with the administrator to
14+
define a pod specification template for the container and to create an
15+
appropriate NNFContainerProfile resource for the container. The image and tag
16+
for the user's container will be specified in the profile.
17+
18+
New NNFContainerProfile resources may be created by copying one of the provided
19+
example profiles from the `nnf-system` namespace. The examples may be found by listing them with `kubectl`:
20+
21+
```console
22+
kubectl get nnfcontainerprofiles -n nnf-system
23+
```
24+
25+
### Workflow Job Specification
26+
27+
The user's workflow will specify the name of the NNFContainerProfile in a DW
28+
directive. If the custom profile is named `red-rock-slushy` then it will be
29+
specified in the "#DW container" directive with the "profile" parameter.
30+
31+
```bash
32+
#DW container profile=red-rock-slushy [...]
33+
```
34+
35+
## Using a Private Container Repository
36+
37+
The user's containerized application may be placed in a private repository. In
38+
this case, the user must define an access token to be used with that repository,
39+
and that token must be made available to the Rabbit's Kubernetes environment
40+
so that it can pull that container from the private repository.
41+
42+
See [Pull an Image from a Private Registry](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) in the Kubernetes documentation
43+
for more information.
44+
45+
### About the Example
46+
47+
Each container registry will have its own way of letting its users create tokens to
48+
be used with their repositories. Docker Hub will be used for the private repository in this example, and the user's account on Docker Hub will be "dean".
49+
50+
### Preparing the Private Repository
51+
52+
The user's application container is named "red-rock-slushy". To store this container
53+
on Docker Hub the user must log into docker.com with their browser and click the "Create repository" button to create a repository named "red-rock-slushy", and the user must check the box that marks the repository as private. The repository's name will be displayed as "dean/red-rock-slushy" with a lock icon to show that it is private.
54+
55+
### Create and Push a Container
56+
57+
The user will create their container image in the usual ways, naming it for their private repository and tagging it according to its release.
58+
59+
Prior to pushing images to the repository, the user must complete a one-time login to the Docker registry using the docker command-line tool.
60+
61+
```console
62+
docker login -u dean
63+
```
64+
65+
After completing the login, the user may then push their images to the repository.
66+
67+
```console
68+
docker push dean/red-rock-slushy:v1.0
69+
```
70+
71+
### Generate a Read-Only Token
72+
73+
A read-only token must be generated to allow Kubernetes to pull that container
74+
image from the private repository, because Kubernetes will not be running as
75+
that user. **This token must be given to the administrator, who will use it to create a Kubernetes secret.**
76+
77+
To log in and generate a read-only token to share with the administrator, the user must follow these steps:
78+
79+
- Visit docker.com and log in using their browser.
80+
- Click on the username in the upper right corner.
81+
- Select "Account Settings" and navigate to "Security".
82+
- Click the "New Access Token" button to create a read-only token.
83+
- Keep a copy of the generated token to share with the administrator.
84+
85+
### Store the Read-Only Token as a Kubernetes Secret
86+
87+
The adminstrator must store the user's read-only token as a kubernetes secret. The
88+
secret must be placed in the `default` namespace, which is the same namespace
89+
where the user containers will be run. The secret must include the user's Docker
90+
Hub username and the email address they have associated with that username. In
91+
this case, the secret will be named `readonly-red-rock-slushy`.
92+
93+
```console
94+
$ USER_TOKEN=users-token-text
95+
$ USER_NAME=dean
96+
$ USER_EMAIL=dean@myco.com
97+
$ SECRET_NAME=readonly-red-rock-slushy
98+
$ kubectl create secret docker-registry $SECRET_NAME -n default --docker-server="https://index.docker.io/v1/" --docker-username=$USER_NAME --docker-password=$USER_TOKEN --docker-email=$USER_EMAIL
99+
```
100+
101+
### Add the Secret to the NNFContainerProfile
102+
103+
The administrator must add an `imagePullSecrets` list to the NNFContainerProfile
104+
resource that was created for this user's containerized application.
105+
106+
The following profile shows the placement of the `readonly-red-rock-slushy` secret
107+
which was created in the previous step, and points to the user's
108+
`dean/red-rock-slushy:v1.0` container.
109+
110+
```yaml
111+
apiVersion: nnf.cray.hpe.com/v1alpha1
112+
kind: NnfContainerProfile
113+
metadata:
114+
name: red-rock-slushy
115+
namespace: nnf-system
116+
data:
117+
pinned: false
118+
retryLimit: 6
119+
spec:
120+
imagePullSecrets:
121+
- name: readonly-red-rock-slushy
122+
containers:
123+
- command:
124+
- /users-application
125+
image: dean/red-rock-slushy:v1.0
126+
name: red-rock-app
127+
storages:
128+
- name: DW_JOB_foo_local_storage
129+
optional: false
130+
- name: DW_PERSISTENT_foo_persistent_storage
131+
optional: true
132+
```
133+
134+
Now any user can select this profile in their Workflow by specifying it in a
135+
`#DW container` directive.
136+
137+
```bash
138+
#DW container profile=red-rock-slushy [...]
139+
```

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ nav:
1515
- 'High Availability Cluster': 'guides/ha-cluster/readme.md'
1616
- 'RBAC for Users': 'guides/rbac-for-users/readme.md'
1717
- 'Storage Profiles': 'guides/storage-profiles/readme.md'
18+
- 'User Containers': 'guides/user-containers/readme.md'
1819
- 'RFCs':
1920
- rfcs/index.md
2021
- 'Rabbit Request For Comment Process': 'rfcs/0001/readme.md'
@@ -45,6 +46,7 @@ extra:
4546
provider: mike
4647
default: latest
4748
markdown_extensions:
49+
- admonition
4850
- pymdownx.highlight:
4951
anchor_linenums: true
5052
- pymdownx.details

0 commit comments

Comments
 (0)