Skip to content

Commit 81970e5

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

5 files changed

+221
-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, 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+
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/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: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
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+
=== Download Projects / Starter Projects
61+
62+
To package projects / starter projects you will need to download them manually then place them under `/stacks/<stack>/<zip>`.
63+
64+
.Procedure
65+
66+
. Zip - Download zip
67+
+
68+
[source,bash]
69+
----
70+
curl -L <remote-url> -o <registry_root>/stacks/<stack>/<project>.zip
71+
----
72+
+
73+
Example
74+
+
75+
[source,bash]
76+
----
77+
cd /path/to/registry
78+
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 \
79+
-o stacks/java-quarkus/community.zip
80+
----
81+
+
82+
. Git - Package cloned contents into a zip
83+
+
84+
[source,bash]
85+
----
86+
git clone <remote-url> <registry_root>/stacks/<stack>/<project>.zip
87+
----
88+
+
89+
Example
90+
+
91+
[source,bash]
92+
----
93+
cd /path/to/registry
94+
git clone https://github.com/odo-devfiles/nodejs-ex.git \
95+
stacks/nodejs/nodejs-starter.zip
96+
----
97+
+
98+
. GitHub - Download repository as a zip archive
99+
+
100+
[source,bash]
101+
----
102+
curl -L https://github.com/<user|org>/<stack_repo_name>/archive/refs/heads/<main_branch>.zip \
103+
-o <registry_root>/stacks/<stack>/<project>.zip
104+
----
105+
+
106+
Example
107+
+
108+
[source,bash]
109+
----
110+
cd /path/to/registry
111+
curl -L https://github.com/odo-devfiles/nodejs-ex/archive/refs/heads/master.zip \
112+
-o stacks/java-quarkus/nodejs-starter.zip
113+
----
114+
115+
=== Modify Devfile
116+
117+
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.
118+
119+
.Starter Project Before
120+
====
121+
----
122+
...
123+
starterProjects:
124+
- name: nodejs-starter
125+
git:
126+
remotes:
127+
origin: https://github.com/odo-devfiles/nodejs-ex.git
128+
...
129+
----
130+
====
131+
132+
.Starter Project After
133+
====
134+
----
135+
...
136+
starterProjects:
137+
- name: nodejs-starter
138+
zip:
139+
location: nodejs-ex.zip
140+
...
141+
----
142+
====
143+
144+
=== Build Registry
145+
146+
.Procedure
147+
148+
. Change to registry root (if not already there)
149+
+
150+
[source,bash]
151+
----
152+
cd /path/to/registry
153+
----
154+
+
155+
. Build Registry Image
156+
+
157+
[source,bash]
158+
----
159+
bash .ci/build.sh
160+
----

‎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 we 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+
. 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.
7+
. 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)