From a4f05c0a7c0530af3e571e7dfacfea1c9af17236 Mon Sep 17 00:00:00 2001 From: Michael Valdron Date: Tue, 7 Jun 2022 20:31:15 -0400 Subject: [PATCH] offline instruction added. Signed-off-by: Michael Valdron --- ...stallation-incluster-registry-offline.adoc | 18 ++ ...-build-and-package-a-devfile-registry.adoc | 161 ++++++++++++++++++ ...stall-a-devfile-registry-to-a-cluster.adoc | 29 ++++ ...tegy-for-refreshing-registry-contents.adoc | 6 + 4 files changed, 214 insertions(+) create mode 100644 docs/modules/user-guide/pages/installation-incluster-registry-offline.adoc create mode 100644 docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc create mode 100644 docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc create mode 100644 docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc diff --git a/docs/modules/user-guide/pages/installation-incluster-registry-offline.adoc b/docs/modules/user-guide/pages/installation-incluster-registry-offline.adoc new file mode 100644 index 00000000..a296d8d2 --- /dev/null +++ b/docs/modules/user-guide/pages/installation-incluster-registry-offline.adoc @@ -0,0 +1,18 @@ +:description: Installation of In-Cluster Offline Devfile Registry +:navtitle: Offline Devfile Registry +:keywords: devfile, registry, stacks + += Installation of In-Cluster Offline Devfile Registry + +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. + +In order to support the air gap installation of the Devfile Registry, the air gap scenario divides into 2 stages: + +. 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. +. Cluster administrators install the Devfile Registry to a cluster to make it available for users to access the registry. + +include::partial$proc_stage-1-build-and-package-a-devfile-registry.adoc[] + +include::partial$proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc[] + +include::partial$proc_update-strategy-for-refreshing-registry-contents.adoc[] diff --git a/docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc b/docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc new file mode 100644 index 00000000..e8abe998 --- /dev/null +++ b/docs/modules/user-guide/partials/proc_stage-1-build-and-package-a-devfile-registry.adoc @@ -0,0 +1,161 @@ +== Stage 1: Build and Package a Devfile Registry + +The main goal of this stage is: + +. Pull in resources into the registry as part of the registry build. +. Modify the Devfile to update references to those offline resources as part of the registry build. + +As part of the offline Devfile registry build, we need to do a few steps. + +.Prerequisites + +* Golang 1.17.x or higher +* Docker 17.05 or higher / Podman 4.0.x or higher +* Git +* Curl +* Unzip + +=== Create Offline Registry + +Download / clone the link:https://github.com/devfile/registry[devfile/registry] repository. + +.Procedure: `git clone` + +* HTTP clone ++ +[source,bash] +---- +git clone https://github.com/devfile/registry.git /path/to/registry +---- ++ +* SSH clone ++ +[source,bash] +---- +git clone git@github.com:devfile/registry.git /path/to/registry +---- + +.Procedure: Download zip + +. Download link:https://github.com/devfile/registry[devfile/registry] ++ +[source,bash] +---- +curl -L https://github.com/devfile/registry/archive/refs/heads/main.zip -o registry.zip +---- ++ +. Unzip registry ++ +[source,bash] +---- +unzip registry.zip -d /path/to/registry +---- + +.Additional resources + +* Creating your own registry Git repository, see xref:building-a-custom-devfile-registry.adoc[Building a custom devfile registry] + +=== Download Projects / Starter Projects + +In order to package projects / starter projects you will need to download them manually then place them under `/stacks//`. + +.Procedure + +. zip - Download zip ++ +[source,bash] +---- +curl -L -o /stacks//.zip +---- ++ +Example ++ +[source,bash] +---- +cd /path/to/registry +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 +---- ++ +. git - Package cloned contents into a zip ++ +[source,bash] +---- +git clone /stacks//.zip +---- ++ +Example ++ +[source,bash] +---- +cd /path/to/registry +git clone https://github.com/odo-devfiles/nodejs-ex.git stacks/nodejs/nodejs-starter.zip +---- ++ +. GitHub - Download repository as a zip archive ++ +[source,bash] +---- +curl -L https://github.com///archive/refs/heads/.zip -o /stacks//.zip +---- ++ +Example ++ +[source,bash] +---- +cd /path/to/registry +curl -L https://github.com/odo-devfiles/nodejs-ex/archive/refs/heads/master.zip -o stacks/java-quarkus/nodejs-starter.zip +---- + +=== Modify Devfile + +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. + +Example + +.Before +[source,yaml] +---- +... +starterProjects: + - name: nodejs-starter + git: + remotes: + origin: 'https://github.com/odo-devfiles/nodejs-ex.git' +... +---- + +.After +[source,yaml] +---- +... +starterProjects: + - name: nodejs-starter + zip: + location: 'nodejs-ex.zip' +... +---- + +=== Build Registry + +.Procedure + +. Clone link:https://github.com/devfile/registry[devfile/registry] ++ +[source,bash] +---- +git clone https://github.com/devfile/registry +---- ++ +. Change to Cloned Repository ++ +[source,bash] +---- +cd registry +---- ++ +. Build Registry Image ++ +[source,bash] +---- +bash .ci/build.sh +---- diff --git a/docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc b/docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc new file mode 100644 index 00000000..e2993b93 --- /dev/null +++ b/docs/modules/user-guide/partials/proc_stage-2-install-a-devfile-registry-to-a-cluster.adoc @@ -0,0 +1,29 @@ +== Stage 2: Install a Devfile Registry to a cluster + +The main goal of this stage (on top of the existing Devfile Registry install mechanism) is to install the images to the image registry. + +=== Install Image into Cluster Image Registry + +The process of installing the built images into an offline image registry will depend on which image registry has deployed / has access to. + +.Procedure + +. OpenShift Image Registry ++ +Retag image using the form `://`. This can be done using `docker tag` or `podman tag`: ++ +[source,bash] +---- +podman tag localhost/devfile-index ://devfile-index +---- ++ +Now we can push the retagged image to the OpenShift Image Registry at `:` by using `docker push` or `podman push`: ++ +[source,bash] +---- +podman push ://devfile-index +---- + +.Additional resources + +* 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] diff --git a/docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc b/docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc new file mode 100644 index 00000000..91c79181 --- /dev/null +++ b/docs/modules/user-guide/partials/proc_update-strategy-for-refreshing-registry-contents.adoc @@ -0,0 +1,6 @@ +== Update strategy for refreshing registry contents + +Steps to update an already deployed registry in the air gap scenario: + +. 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. +. Cluster administrators update the existing Devfile Registry deployment with the new Devfile Registry to make it available for users to access the registry.