Complete documentation coverage of registry operator

CONTRIBUTING.md

@@ -17,10 +17,7 @@ You can tag Devfile Registry related issues with the `/area registry` text in yo
 ### Development
 
 #### First Time Setup
-1. Install prerequisites:
-   - Go 1.13 or higher
-   - Docker or Podman
-   - Operator-SDK 1.11.0 or higher (including `controller-gen` 0.6.0 or higher)
+1. Install prerequisites: see [Requirements section in README](README.md#requirements).
 
 2. Fork and clone this repository.
 
@@ -35,9 +32,11 @@ You can tag Devfile Registry related issues with the `/area registry` text in yo
 
 4. Run `make docker-push` to push the devfile registry operator image.
 
-5. Run `make install` to install the CRDs
+5. Run `make install-cert` to install the cert-manager.
 
-6. Run `make deploy` to deploy the operator.
+6. Run `make install` to install the CRDs.
+
+7. Run `make deploy` to deploy the operator.
 
 ### Testing your Changes
 
@@ -55,7 +54,7 @@ To run these tests, run the following commands :
 
 ```bash
 export IMG=<your-built-operator-image>
-make test_integration
+make test-integration
 ```
 
 

DEVFILE_REGISTRY.md

@@ -4,14 +4,14 @@ The Devfile Registry custom resource allows you to create and manage your own in
 
 ## Deploying a Devfile Registry
 
-Once the Devfile Registry operator has been deployed to a cluster, it's straightforward to deploy a Devfile Registry. The following samples below showcase how the registry can be deployed on to an OpenShift or Kubernetes cluster.
+Once the Devfile Registry operator has been deployed to a cluster, you can deploy a Devfile Registry by creating custom resources. The following samples below showcase how the registry can be deployed on to an OpenShift or Kubernetes cluster.
 
 In addition to the examples below, the `samples/` folder in this repo provides some example devfile registry yaml files for convenience.
 
 
 ### OpenShift
 
-Installing the devfile registry via the devfile registry operator on an OpenShift cluster can be done in one easy command:
+Installing the devfile registry via the devfile registry operator on an OpenShift cluster can be done with this command:
 
 ```bash
 $ cat <<EOF | oc apply -f -
@@ -30,7 +30,7 @@ EOF
 
 ### Kubernetes
 
-Installing the devfile registry on a Kubernetes cluster is similar, but requires setting the `k8s.ingressDomain` field first.
+Installing the devfile registry on a Kubernetes cluster is similar, but requires setting the `k8s.ingressDomain` field.
 
 ```bash
 $ export INGRESS_DOMAIN=<my-ingress-domain>
@@ -61,3 +61,146 @@ If you want to send telemetry information to your own Segment instance, specify
     key: <your-segment-write-key>
     registryViewerWriteKey: <your-segment-write-key>
 ```
+
+## Using Specific Container Images
+
+By default, the operator deploys a Devfile Registry using a Pod containing three containers:
+
+- `devfile-registry` container runs the API serving the Devfile stacks. The container image used by default
+is `quay.io/devfile/devfile-index:next` and you can change it with the field `spec.devfileIndex.image`.
+- `oci-registry` container runs a standard OCI registry, serving the stacks in the OCI format.
+The container image used by default is `quay.io/devfile/oci-registry:next` and you can change it with the field `spec.ociRegistry.image`.
+- `registry-viewer` container runs a web frontend, to help the user brwose the Devfile stacks.
+The container image used by default is `quay.io/devfile/registry-viewer:next` and you can change it with the field `spec.registryViewer.image`.
+
+```bash
+$ cat <<EOF | oc apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: my-devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/my-devfile/devfile-index:next
+  ociRegistry:
+    image: quay.io/my-devfile/oci-registry:next
+  registryViewer:
+    image: quay.io/my-devfile/registry-viewer:next
+EOF
+```
+
+### Defining the ImagePullPolicy for pulling containers
+
+By default, the containers will be pulled depending on the policy set on the Kubernetes or OpenShift cluster the registry is deployed on.
+
+You can set a specific pull policy for each container, by setting the fields `spec.devfileIndex.imagePullPolicy`, `spec.ociRegistry.imagePullPolicy` and `spec.registryViewer.imagePullPolicy` to a value `IfNotPresent`, `Always` or `Never`. See the [Kubernetes documentation](https://kubernetes.io/docs/concepts/containers/images/#image-pull-policy) for more information.
+
+
+```bash
+$ cat <<EOF | oc apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: my-devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/my-devfile/devfile-index:next
+    imagePullPolicy: Always
+  ociRegistry:
+    image: quay.io/my-devfile/oci-registry:next
+    imagePullPolicy: Always
+  registryViewer:
+    image: quay.io/my-devfile/registry-viewer:next
+    imagePullPolicy: Always
+EOF
+```
+
+## Disabling the web frontend 
+
+You can ask the operator to deploy the Devfile Registry without the `registry-viewer` container, by setting the field `spec.headless` to `true`.
+
+```bash
+$ cat <<EOF | oc apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: headless-devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/devfile/devfile-index:next
+  telemetry:
+    registryName: test
+  headless: true
+EOF
+```
+
+## Configuring TLS for Ingress/Route resource
+
+The operator creates a Route resource (on OpenShift) or an Ingress resources (on Kubernetes)
+to give access to the Web frontend.
+
+By default, the Ingress or Route is secured by TLS.
+
+You can ask the operator to disable the use of TLS by setting the field `spec.tls.enabled` to false.
+
+```bash
+$ cat <<EOF | kubectl apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/devfile/devfile-index:next
+  telemetry:
+    registryName: test
+  tls:
+    enabled: false
+EOF
+```
+
+You can ask the operator to configure the TLS with a specific certificate, by specifying a secret
+containing the certificate and the associated private key using the field `spec.tls.secretName`:
+
+```bash
+$ kubectl create secret tls my-tls-secret --key=certs/ingress-tls.key --cert=certs/ingress-tls.crt
+
+$ cat <<EOF | kubectl apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/devfile/devfile-index:next
+  telemetry:
+    registryName: test
+  tls:
+    enabled: true
+    secretName: my-tls-secret
+EOF
+```
+
+## Configuring the Ingress Domain
+
+On Kubernetes, the operator needs to know the Domain associated with the cluster, to create an Ingress
+with this specific domain. You need to indicate the Ingress domain with the field `spec.k8s.ingressDomain`.
+
+
+```bash
+$ export INGRESS_DOMAIN=<my-ingress-domain>
+
+$ cat <<EOF | kubectl apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistry
+metadata:
+  name: devfile-registry
+spec:
+  devfileIndex:
+    image: quay.io/devfile/devfile-index:next
+  telemetry:
+    registryName: test
+  k8s:
+    ingressDomain: $INGRESS_DOMAIN
+EOF
+```

README.md

@@ -60,6 +60,8 @@ Some of the rules supported by the makefile:
 
 |rule|purpose|
 |---|---|
+| controller-gen | install the controll-gen tool, used by other commands |
+| kustomize | install the kustomize tool, used by other commands |
 | docker-build | build registry operator docker image |
 | docker-push | push registry operator docker image |
 | deploy | deploy operator to cluster |
@@ -71,34 +73,52 @@ Some of the rules supported by the makefile:
 | manifests | Generate manifests e.g. CRD, RBAC etc. |
 | generate | Generate the API type definitions. Must be run after modifying the DevfileRegistry type. |
 | bundle | Generate bundle manifests and metadata, then validate generated files. |
-| test_integration | Run the integration tests for the operator. |
+| test-integration | Run the integration tests for the operator. |
 | test | Run the unit tests for the operator. |
+| fmt | Check code formatting |
+| fmt_license | Ensure license header is set on all files |
+| vet | Check suspicious constructs into code |
+| gosec | Check for security problems in non-test source files |
 
 To see all rules supported by the makefile, run `make help`
 
 ## Testing
 
 To run integration tests for the operator, run `make test-integration`. 
 
-By default, the tests will use the default image for the operator, `quay.io/devfile/registry-operator:next`. To use your own image, run:
+The `oc` executable must be accessible.
+
+By default, the tests will use the default image for the operator, `quay.io/devfile/registry-operator:next`.
+
+You can use `make docker-build` to build your own image, `make docker-push` to publish it. Then, to use your own image, run:
 
 ```
-export IMG=<your-operator-image>
-make test-integration
+IMG=<your-operator-image> make test-integration
 ```
 
 ### Run operator locally
 It's possible to run an instance of the operator locally while communicating with a cluster. 
 
-1. Build the binary
+1. You may need to install the `controller-gen` tool before, used when building the binary:
+
+```bash
+make controller-gen
+```
+
+2. Build the binary
 
 ```bash
 make manager
 ```
 
-2. Run the controller
+3. Deploy the CRDs
+
+```bash
+make install
+```
+
+4. Run the controller
 
 ```bash
-export NAMESPACE=devfileregistry-operator
 make run ENABLE_WEBHOOKS=false
 ```

REGISTRIES_LISTS.md

@@ -1,13 +1,13 @@
 # Registries Lists
 
-The Cluster/Devfile Registries Lists allow admins to specify multiple devfile registries to expose devfiles from various sources for use within the cluster or namespace.  In order to be added to the list, the devfile registries must be reachable and support the Devfile v2.0 spec and above.
+The Devfile Registries Lists allow admins to specify multiple devfile registries to expose devfiles from various sources for use within the cluster or namespace.  In order to be added to the list, the devfile registries must be reachable and support the Devfile v2.0 spec and above.
 
 >**ClusterDevfileRegistriesList** is a custom resource where cluster admins can add a list of devfile registries to allow devfiles to be visible at the cluster level.  
 
 
 > **DevfileRegistriesList** is a custom resource where cluster admins can add a list of devfile registries to allow devfiles to be visible at the namespace level.  Registries in this list will take precedence over the ones in the ClusterDevfileRegistriesList if there is a conflict.
 
-## Deploying a Cluster or Devfile Registries List
+## Deploying a Cluster or Namespaced Devfile Registries List
 
 Note the following limitations when deploying a new list type:
 * Only one ClusterDevfileRegistriesList can be installed per cluster.  If there is an existing list, you will encounter a validation error.
@@ -49,7 +49,41 @@ spec:
 EOF
 ```
 
+#### Skipping the TLS Verification
 
+The operator contacts each Devfile Registry of the list, to check its validity.
+
+In a non-production environment, you may want the operator to Skip the TLS Verification during this call, by setting the field `skipTLSVerify` for the Devfile Registry:
+
+```bash
+$ cat <<EOF | kubectl apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: ClusterDevfileRegistriesList
+metadata:
+  name: cluster-list
+spec:
+  devfileRegistries:
+    - name: devfile-staging
+      url: 'https://registry.stage.devfile.io'
+      skipTLSVerify: true
+EOF
+```
+
+ or
+
+```bash
+$ cat <<EOF | kubectl apply -f -
+apiVersion: registry.devfile.io/v1alpha1
+kind: DevfileRegistriesList
+metadata:
+  name: namespace-list
+spec:
+  devfileRegistries:
+    - name: devfile-staging
+      url: 'https://registry.stage.devfile.io'
+      skipTLSVerify: true
+EOF
+```
 
 ## Updating the Cluster or Devfile Registries List
 

api/v1alpha1/devfileregistry_types.go

@@ -81,7 +81,7 @@ type DevfileRegistrySpecStorage struct {
 	// Configures the size of the devfile registry's persistent volume, if enabled.
 	// Defaults to 1Gi.
 	// +optional
-	RegistryVolumeSize string `json:"ociRegistryImage,omitempty"`
+	RegistryVolumeSize string `json:"registryVolumeSize,omitempty"`
 }
 
 // DevfileRegistrySpecTLS defines the desired state for TLS in the DevfileRegistry
@@ -93,7 +93,7 @@ type DevfileRegistrySpecTLS struct {
 
 	// Name of an optional, pre-existing TLS secret to use for TLS termination on ingress/route resources.
 	// +optional
-	SecretName string `json:"ociRegistryImage,omitempty"`
+	SecretName string `json:"secretName,omitempty"`
 }
 
 // DevfileRegistrySpecK8sOnly defines the desired state of the kubernetes-only fields of the DevfileRegistry

bundle/manifests/registry.devfile.io_devfileregistries.yaml

@@ -108,7 +108,7 @@ spec:
                     description: Instructs the operator to deploy the DevfileRegistry
                       with persistent storage Disabled by default.
                     type: boolean
-                  ociRegistryImage:
+                  registryVolumeSize:
                     description: Configures the size of the devfile registry's persistent
                       volume, if enabled. Defaults to 1Gi.
                     type: string
@@ -142,7 +142,7 @@ spec:
                       with TLS enabled. Enabled by default. Disabling is only recommended
                       for development or test.
                     type: boolean
-                  ociRegistryImage:
+                  secretName:
                     description: Name of an optional, pre-existing TLS secret to use
                       for TLS termination on ingress/route resources.
                     type: string

config/crd/bases/registry.devfile.io_devfileregistries.yaml

@@ -109,7 +109,7 @@ spec:
                     description: Instructs the operator to deploy the DevfileRegistry
                       with persistent storage Disabled by default.
                     type: boolean
-                  ociRegistryImage:
+                  registryVolumeSize:
                     description: Configures the size of the devfile registry's persistent
                       volume, if enabled. Defaults to 1Gi.
                     type: string
@@ -143,7 +143,7 @@ spec:
                       with TLS enabled. Enabled by default. Disabling is only recommended
                       for development or test.
                     type: boolean
-                  ociRegistryImage:
+                  secretName:
                     description: Name of an optional, pre-existing TLS secret to use
                       for TLS termination on ingress/route resources.
                     type: string