Skip to content

Commit 8b48c9c

Browse files
michael-valdronmichael-valdron
committed
offline instruction added.
Signed-off-by: Michael Valdron <[email protected]>
1 parent 54dcd54 commit 8b48c9c

5 files changed

+241
-1
lines changed

‎docs/modules/user-guide/pages/installation-incluster-registry-offline.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, for example container images and starter projects. The current devfile registry currently does not store those supporting resources as part of the registry. This means that a user will need to 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 2 stages:
10+
11+
. Build a devfile registry based on one or more source repositories, e.g. link:https://github.com/devfile/registry[devfile/registry], to build and package up a devfile registry that 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: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,4 @@ Get started with devfile registries:
2323
* xref:creating-a-devfile-stack.adoc[]
2424
* xref:adding-a-stack-yaml-file.adoc[]
2525
26-
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: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
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+
As part of the offline devfile registry build, we need to do a few steps.
10+
11+
.Prerequisites
12+
13+
* Golang 1.17.x or higher
14+
* Docker 17.05 or higher / Podman 4.0.x or higher
15+
* Git
16+
* Curl
17+
* Unzip
18+
19+
=== Create Offline Registry
20+
21+
Download / clone the link:https://github.com/devfile/registry[devfile/registry] repository.
22+
23+
.Procedure: `git clone`
24+
25+
* HTTP clone
26+
+
27+
[source,bash]
28+
----
29+
git clone https://github.com/devfile/registry.git /path/to/registry
30+
----
31+
+
32+
* SSH clone
33+
+
34+
[source,bash]
35+
----
36+
git clone [email protected]:devfile/registry.git /path/to/registry
37+
----
38+
39+
.Procedure: Download zip
40+
41+
. Download link:https://github.com/devfile/registry[devfile/registry]
42+
+
43+
[source,bash]
44+
----
45+
curl -L https://github.com/devfile/registry/archive/refs/heads/main.zip \
46+
-o registry.zip
47+
----
48+
+
49+
. Unzip registry
50+
+
51+
[source,bash]
52+
----
53+
unzip registry.zip -d /path/to/registry
54+
----
55+
56+
.Additional resources
57+
58+
* Creating your own registry Git repository, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]
59+
60+
=== Packaging Starter Projects
61+
62+
To package starter projects you will need to download them manually then place them under `/stacks/<stack>/<zip>-offline.zip`.
63+
64+
*Note*: Starter projects must be packaged under a zip archive with the suffix `-offline` to be pulled into the registry.
65+
66+
.Procedure
67+
68+
. Zip - Download zip
69+
+
70+
[source,bash]
71+
----
72+
curl -L <remote-url> -o <registry_root>/stacks/<stack>/<project>-offline.zip
73+
----
74+
+
75+
Example
76+
+
77+
[source,bash]
78+
----
79+
cd /path/to/registry
80+
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 \
81+
-o stacks/java-quarkus/community-offline.zip
82+
----
83+
+
84+
. Git - Package cloned contents into a zip
85+
+
86+
[source,bash]
87+
----
88+
git clone <remote-url> <registry_root>/stacks/<stack>/<project>-offline.zip
89+
----
90+
+
91+
Example
92+
+
93+
[source,bash]
94+
----
95+
cd /path/to/registry
96+
git clone https://github.com/odo-devfiles/nodejs-ex.git \
97+
stacks/nodejs/nodejs-starter-offline.zip
98+
----
99+
+
100+
. GitHub - Download repository as a zip archive
101+
+
102+
[source,bash]
103+
----
104+
curl -L https://github.com/<user|org>/<stack_repo_name>/archive/refs/heads/<main_branch>.zip \
105+
-o <registry_root>/stacks/<stack>/<project>-offline.zip
106+
----
107+
+
108+
Example
109+
+
110+
[source,bash]
111+
----
112+
cd /path/to/registry
113+
curl -L https://github.com/odo-devfiles/nodejs-ex/archive/refs/heads/master.zip \
114+
-o stacks/java-quarkus/nodejs-starter-offline.zip
115+
----
116+
117+
=== Modify Devfile
118+
119+
Modification is to the devfile will be needed to 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.
120+
121+
.Procedure
122+
123+
. Under `starterProjects`, find the starter project definition you want to make offline
124+
. Under the definition for the starter project find either `git` or `zip`, as seen here:
125+
+
126+
.Starter Project Before
127+
====
128+
----
129+
...
130+
starterProjects:
131+
- name: nodejs-starter
132+
git:
133+
remotes:
134+
origin: https://github.com/odo-devfiles/nodejs-ex.git
135+
...
136+
----
137+
====
138+
+
139+
. Do one of the following depending on the block type:
140+
* 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>/`).
141+
* If `zip`, just replace the value of `location` to the same as mention for `git`.
142+
. In either case, you should end up with something like as seen here:
143+
+
144+
.Starter Project After
145+
====
146+
----
147+
...
148+
starterProjects:
149+
- name: nodejs-starter
150+
zip:
151+
location: nodejs-starter-offline.zip
152+
...
153+
----
154+
====
155+
156+
.Additional resources
157+
158+
* More about starter projects in devfiles, see xref:adding-projects-to-a-devfile.adoc[Adding projects to a devfile]
159+
160+
=== Build Registry
161+
162+
.Procedure
163+
164+
. Change to registry root (if not already there)
165+
+
166+
[source,bash]
167+
----
168+
cd /path/to/registry
169+
----
170+
+
171+
. Build Registry Image
172+
+
173+
[source,bash]
174+
----
175+
bash .ci/build.sh
176+
----
177+
178+
.Additional resources
179+
180+
* 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: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
[id="stage-2-install-a-devfile-registry-to-a-cluster_{context}"]
2+
== Stage 2: Install a Devfile Registry to a cluster
3+
4+
The main goal of this stage (on top of the existing devfile registry install mechanism) is to install the images to the image registry.
5+
6+
.Prerequisites
7+
8+
* Docker 17.05 or higher / Podman 4.0.x or higher
9+
* OpenShift Container Platform 4.6 or higher
10+
11+
=== Install Image into Cluster Image Registry
12+
13+
The process of installing the built images into an offline image registry will depend on which image registry has deployed / has access to.
14+
15+
.Procedure
16+
17+
. OpenShift Image Registry
18+
+
19+
Retag image using the form `<registry_ip>:<port>/<project>/<image>`. This can be done using `docker tag` or `podman tag`:
20+
+
21+
[source,bash]
22+
----
23+
podman tag localhost/devfile-index <registry_ip>:<port>/<project>/devfile-index
24+
----
25+
+
26+
Now you can push the retagged image to the OpenShift Image Registry at `<registry_ip>:<port>` by using `docker push` or `podman push`:
27+
+
28+
[source,bash]
29+
----
30+
podman push <registry_ip>:<port>/<project>/devfile-index
31+
----
32+
33+
.Additional resources
34+
35+
* 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+
. Rerun the registry build script to rebuild the devfile registry and package up the devfile registry that contains all the resources available for offline installation.
7+
. Update the existing devfile registry deployment with the new devfile registry to make it available for users to access the registry.

0 commit comments

Comments
 (0)