Skip to content

Commit f2085ec

Browse files
michael-valdronmichael-valdron
authored
In-cluster offline devfile registry installation manual instruction added (#159)
Signed-off-by: Michael Valdron <[email protected]>
1 parent 9e7753b commit f2085ec

5 files changed

+232
-1
lines changed

‎docs/modules/user-guide/pages/installation-of-incluster-offline-devfile-registry.adoc

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
:description: Installation of In-Cluster Offline Devfile Registry
2+
:navtitle: Offline Devfile Registry
3+
:keywords: devfile, registry, stacks
4+
5+
= Installation of In-Cluster Offline Devfile Registry
6+
7+
A devfile refers to various resources, such as container images and starter projects. The current devfile registry currently does not store those supporting resources. Therefore, you must have access to those resources when using those devfiles.
8+
9+
To support the air gap installation of the devfile registry, the air gap scenario divides into two stages:
10+
11+
. Build a devfile registry based on one or more source repositories so that the registry contains all the resources available for offline installation.
12+
. Install the devfile registry to a cluster to make it available for users to access the registry.
13+
14+
include::partial$proc_stage-1-build-and-package-a-devfile-registry.adoc[]
15+
16+
include::partial$proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc[]
17+
18+
include::partial$proc_update-strategy-for-refreshing-registry-contents.adoc[]

‎docs/modules/user-guide/partials/assembly_devfile-registry.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@ Get started with devfile registries:
1717

1818
* xref:understanding-a-devfile-registry.adoc[]
1919
* xref:building-a-custom-devfile-registry.adoc[]
20+
* xref:installation-of-incluster-offline-devfile-registry.adoc[]
2021
* xref:deploying-a-devfile-registry.adoc[]
2122
* xref:adding-a-registry-schema.adoc[]
2223
* xref:creating-a-devfile-stack.adoc[]
2324
* xref:adding-a-stack-yaml-file.adoc[]
2425
25-
For more information on the devfile registry, see the link:https://github.com/devfile/registry-support/blob/main/index/server/registry-REST-API.adoc[Registry REST API].
26+
For more information about the devfile registry, see the link:https://github.com/devfile/registry-support/blob/main/index/server/registry-REST-API.adoc[Registry REST API].

‎docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
[id="stage-1-build-and-package-a-devfile-registry_{context}"]
2+
== Stage 1: Build and Package a Devfile Registry
3+
4+
The main goal of this stage is:
5+
6+
. Pull in resources into the registry as part of the registry build.
7+
. Modify the devfile to update references to those offline resources as part of the registry build.
8+
9+
.Prerequisites
10+
11+
* Golang 1.17.x or higher
12+
* Docker 17.05 or higher or Podman 4.0.x or higher
13+
* Git
14+
* Curl
15+
* Archive Tools (such as `unzip`)
16+
17+
=== Create Offline Registry
18+
19+
Download / clone the link:https://github.com/devfile/registry[devfile/registry] repository.
20+
21+
.Procedure
22+
23+
* Clone through HTTPS
24+
+
25+
[source,bash]
26+
----
27+
git clone https://github.com/devfile/registry.git /path/to/registry
28+
----
29+
+
30+
* Clone through SSH
31+
+
32+
[source,bash]
33+
----
34+
git clone [email protected]:devfile/registry.git /path/to/registry
35+
----
36+
37+
.Additional resources
38+
39+
* To create your own registry Git repository, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]
40+
41+
=== Install Stack Images
42+
43+
You will first need to collect all the image tags used in the stacks needed for offline access. The image tags collected are to each be pulled, re-tagged, and installed into the image repository accessible by the offline cluster. Procedure here will require you to **change the devfile**.
44+
45+
.Procedure
46+
. Use the `docker pull` or the `podman pull` to pull down an image for a stack component:
47+
+
48+
[source,bash]
49+
----
50+
podman pull registry.access.redhat.com/ubi8/nodejs-16:latest
51+
----
52+
+
53+
. Use the `docker tag` or the `podman tag` to re-tag the image that uses the form `<registry_host>:<port>/<project>/<image>`:
54+
+
55+
[source,bash]
56+
----
57+
podman tag registry.access.redhat.com/ubi8/nodejs-16:latest \
58+
<registry_host>:<port>/<project>/nodejs-16:latest
59+
----
60+
+
61+
. Use the `docker push` or `podman push` to push the re-tagged image to the image repository at `<registry_host>:<port>`:
62+
+
63+
[source,bash]
64+
----
65+
podman push <registry_host>:<port>/<project>/nodejs-16:latest
66+
----
67+
68+
.Additional resources
69+
70+
* For more on interacting with the OpenShift Image Registry, see link:https://docs.openshift.com/container-platform/4.10/registry/accessing-the-registry.html[Accessing the registry]
71+
72+
=== Packaging Starter Projects
73+
74+
To package starter projects you will need to download them manually then place them under `/stacks/<stack>/<zip>-offline.zip`. Procedure here will require you to **change the devfile**.
75+
76+
*Note*: Starter projects must be packaged under an archive with the suffix `-offline` to be pulled into the registry.
77+
78+
.Procedure
79+
80+
. `zip` - Download archive
81+
+
82+
Example
83+
+
84+
[source,bash]
85+
----
86+
cd /path/to/registry
87+
curl -L https://code.quarkus.io/d?e=io.quarkus%3Aquarkus-resteasy&e=io.quarkus%3Aquarkus-micrometer&e=io.quarkus%3Aquarkus-smallrye-health&e=io.quarkus%3Aquarkus-openshift&cn=devfile \
88+
-o stacks/java-quarkus/community-offline.zip
89+
----
90+
+
91+
. `git` - Package cloned contents into a directory then archive
92+
+
93+
Example
94+
+
95+
[source,bash]
96+
----
97+
cd /path/to/registry
98+
git clone https://github.com/odo-devfiles/nodejs-ex.git \
99+
stacks/nodejs/nodejs-starter-offline
100+
cd stacks/nodejs
101+
zip -r nodejs-starter-offline.zip nodejs-starter-offline
102+
----
103+
104+
=== Modify Devfile
105+
106+
Change the devfile so you can update references to those offline resources as part of the registry build. For all the items pulled into the registry, update the corresponding devfile entries to reference the resources within the offline version in the registry:
107+
108+
. All location references to `starterProjects` will change to local paths relative to the stacks directory.
109+
. Stack component image references will change to use the offline accessible image repository.
110+
111+
.Procedure
112+
113+
. Under `starterProjects`, find the starter project definition you want to make offline.
114+
. Under the definition for the starter project find either `git` or `zip`:
115+
+
116+
.Starter Project Before
117+
====
118+
----
119+
...
120+
starterProjects:
121+
- name: nodejs-starter
122+
git:
123+
remotes:
124+
origin: https://github.com/odo-devfiles/nodejs-ex.git
125+
...
126+
----
127+
====
128+
+
129+
. Do one of the following depending on the block type:
130+
* If `git`, replace all of the `git` block with a `zip` block and add the `location` to be the path to the local file under the stack root directory (`<registry_root>/stacks/<stack>/`).
131+
* If `zip`, just replace the value of `location` to the local file under the stack root directory (`<registry_root>/stacks/<stack>/`).
132+
133+
.Verification step
134+
135+
To confirm you modified your devfile, verify your altered starter project definition is similar to the following example:
136+
137+
.Altered Starter Project Definition
138+
====
139+
----
140+
...
141+
starterProjects:
142+
- name: nodejs-starter
143+
zip:
144+
location: nodejs-starter-offline.zip
145+
...
146+
----
147+
====
148+
149+
.Additional resources
150+
151+
* To learn more about starter projects in devfiles, see xref:adding-projects-to-a-devfile.adoc[Adding projects to a devfile]
152+
153+
=== Build Registry
154+
155+
.Procedure
156+
157+
. If not already at the root of the registry, change to the root of the registry.
158+
+
159+
[source,bash]
160+
----
161+
cd /path/to/registry
162+
----
163+
+
164+
. Build the registry image.
165+
+
166+
[source,bash]
167+
----
168+
bash .ci/build.sh
169+
----
170+
171+
.Additional resources
172+
173+
* For more information about building your own registry image, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]

‎docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
[id="stage-2-install-a-devfile-registry-to-a-cluster_{context}"]
2+
== Stage 2: Install a Devfile Registry to a cluster
3+
4+
In this stage, you will push the container images to a registry available to the offline cluster.
5+
6+
.Prerequisites
7+
8+
* Docker 17.05 or higher or Podman 4.0.x or higher
9+
10+
=== Install Image into Cluster Image Registry
11+
12+
The process of installing the built images into an offline image registry depends on which image registry has deployed and which image registry you have access to.
13+
14+
.Procedure
15+
16+
. Use the `docker tag` or the `podman tag` to re-tag the image using the form `<registry_host>:<port>/<project>/<image>`:
17+
+
18+
[source,bash]
19+
----
20+
podman tag devfile-index <registry_host>:<port>/<project>/devfile-index
21+
----
22+
+
23+
. Use the `docker push` or `podman push` to push the re-tagged image to the cluster image registry at `<registry_host>:<port>`:
24+
+
25+
[source,bash]
26+
----
27+
podman push <registry_host>:<port>/<project>/devfile-index
28+
----
29+
30+
.Additional resources
31+
32+
* For more on interacting with the OpenShift Image Registry, see link:https://docs.openshift.com/container-platform/4.10/registry/accessing-the-registry.html[Accessing the registry]

‎docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[id="update-strategy-for-refreshing-registry-contents_{context}"]
2+
== Update strategy for refreshing registry contents
3+
4+
Steps to update an already deployed registry in the air gap scenario:
5+
6+
. Follow offline registry instructions in the above sections and rerun the registry build script to rebuild the devfile registry.
7+
. Update the existing offline devfile registry deployment with a newly built and updated offline devfile registry image.

0 commit comments

Comments
 (0)