Skip to content

Commit a4f05c0

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

4 files changed

+214
-0
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, e.g. container images, projects, and starter projects. The current Devfile registry currently does not store those supporting resources as part of the registry. This means that the user will need to have access to those resources when using those Devfiles.
8+
9+
In order to support the air gap installation of the Devfile Registry, the air gap scenario divides into 2 stages:
10+
11+
. Devfile registry administrator 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+
. Cluster administrators 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/proc_stage-1-build-and-package-a-devfile-registry.adoc

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
== Stage 1: Build and Package a Devfile Registry
2+
3+
The main goal of this stage is:
4+
5+
. Pull in resources into the registry as part of the registry build.
6+
. Modify the Devfile to update references to those offline resources as part of the registry build.
7+
8+
As part of the offline Devfile registry build, we need to do a few steps.
9+
10+
.Prerequisites
11+
12+
* Golang 1.17.x or higher
13+
* Docker 17.05 or higher / Podman 4.0.x or higher
14+
* Git
15+
* Curl
16+
* Unzip
17+
18+
=== Create Offline Registry
19+
20+
Download / clone the link:https://github.com/devfile/registry[devfile/registry] repository.
21+
22+
.Procedure: `git clone`
23+
24+
* HTTP clone
25+
+
26+
[source,bash]
27+
----
28+
git clone https://github.com/devfile/registry.git /path/to/registry
29+
----
30+
+
31+
* SSH clone
32+
+
33+
[source,bash]
34+
----
35+
git clone [email protected]:devfile/registry.git /path/to/registry
36+
----
37+
38+
.Procedure: Download zip
39+
40+
. Download link:https://github.com/devfile/registry[devfile/registry]
41+
+
42+
[source,bash]
43+
----
44+
curl -L https://github.com/devfile/registry/archive/refs/heads/main.zip -o registry.zip
45+
----
46+
+
47+
. Unzip registry
48+
+
49+
[source,bash]
50+
----
51+
unzip registry.zip -d /path/to/registry
52+
----
53+
54+
.Additional resources
55+
56+
* Creating your own registry Git repository, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry]
57+
58+
=== Download Projects / Starter Projects
59+
60+
In order to package projects / starter projects you will need to download them manually then place them under `/stacks/<stack>/<zip>`.
61+
62+
.Procedure
63+
64+
. zip - Download zip
65+
+
66+
[source,bash]
67+
----
68+
curl -L <remote-url> -o <registry_root>/stacks/<stack>/<project>.zip
69+
----
70+
+
71+
Example
72+
+
73+
[source,bash]
74+
----
75+
cd /path/to/registry
76+
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 -o stacks/java-quarkus/community.zip
77+
----
78+
+
79+
. git - Package cloned contents into a zip
80+
+
81+
[source,bash]
82+
----
83+
git clone <remote-url> <registry_root>/stacks/<stack>/<project>.zip
84+
----
85+
+
86+
Example
87+
+
88+
[source,bash]
89+
----
90+
cd /path/to/registry
91+
git clone https://github.com/odo-devfiles/nodejs-ex.git stacks/nodejs/nodejs-starter.zip
92+
----
93+
+
94+
. GitHub - Download repository as a zip archive
95+
+
96+
[source,bash]
97+
----
98+
curl -L https://github.com/<user|org>/<repo_name>/archive/refs/heads/<main_branch>.zip -o <registry_root>/stacks/<stack>/<project>.zip
99+
----
100+
+
101+
Example
102+
+
103+
[source,bash]
104+
----
105+
cd /path/to/registry
106+
curl -L https://github.com/odo-devfiles/nodejs-ex/archive/refs/heads/master.zip -o stacks/java-quarkus/nodejs-starter.zip
107+
----
108+
109+
=== Modify Devfile
110+
111+
We need to modify the Devfile 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.
112+
113+
Example
114+
115+
.Before
116+
[source,yaml]
117+
----
118+
...
119+
starterProjects:
120+
- name: nodejs-starter
121+
git:
122+
remotes:
123+
origin: 'https://github.com/odo-devfiles/nodejs-ex.git'
124+
...
125+
----
126+
127+
.After
128+
[source,yaml]
129+
----
130+
...
131+
starterProjects:
132+
- name: nodejs-starter
133+
zip:
134+
location: 'nodejs-ex.zip'
135+
...
136+
----
137+
138+
=== Build Registry
139+
140+
.Procedure
141+
142+
. Clone link:https://github.com/devfile/registry[devfile/registry]
143+
+
144+
[source,bash]
145+
----
146+
git clone https://github.com/devfile/registry
147+
----
148+
+
149+
. Change to Cloned Repository
150+
+
151+
[source,bash]
152+
----
153+
cd registry
154+
----
155+
+
156+
. Build Registry Image
157+
+
158+
[source,bash]
159+
----
160+
bash .ci/build.sh
161+
----

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
== Stage 2: Install a Devfile Registry to a cluster
2+
3+
The main goal of this stage (on top of the existing Devfile Registry install mechanism) is to install the images to the image registry.
4+
5+
=== Install Image into Cluster Image Registry
6+
7+
The process of installing the built images into an offline image registry will depend on which image registry has deployed / has access to.
8+
9+
.Procedure
10+
11+
. OpenShift Image Registry
12+
+
13+
Retag image using the form `<registry_ip>:<port>/<project>/<image>`. This can be done using `docker tag` or `podman tag`:
14+
+
15+
[source,bash]
16+
----
17+
podman tag localhost/devfile-index <registry_ip>:<port>/<project>/devfile-index
18+
----
19+
+
20+
Now we can push the retagged image to the OpenShift Image Registry at `<registry_ip>:<port>` by using `docker push` or `podman push`:
21+
+
22+
[source,bash]
23+
----
24+
podman push <registry_ip>:<port>/<project>/devfile-index
25+
----
26+
27+
.Additional resources
28+
29+
* 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: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
== Update strategy for refreshing registry contents
2+
3+
Steps to update an already deployed registry in the air gap scenario:
4+
5+
. Devfile registry administrator 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.
6+
. Cluster administrators 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)