|
| 1 | +## Provider Contract |
| 2 | + |
| 3 | +### Invoking manifests-gen |
| 4 | + |
| 5 | +`manifests-gen` is typically invoked in a provider repo from a `ocp-manifests` target in `openshift/Makfile`. |
| 6 | +For example, the invocation for cluster-api-provider-aws might look like this: |
| 7 | +```make |
| 8 | +.PHONY: ocp-manifests |
| 9 | +ocp-manifests: | $(RELEASE_DIR) ## Builds openshift specific manifests |
| 10 | + # Generate provider manifests. |
| 11 | + cd tools && $(MANIFESTS_GEN) --manifests-path "../capi-operator-manifests" --kustomize-dir="../../openshift" \ |
| 12 | + --name cluster-api-provider-aws \ |
| 13 | + --attribute type=infrastructure \ |
| 14 | + --attribute version="${PROVIDER_VERSION}" \ |
| 15 | + --self-image-ref registry.ci.openshift.org/openshift:aws-cluster-api-controllers \ |
| 16 | + --platform AWS \ |
| 17 | + --protect-cluster-resource awscluster |
| 18 | +``` |
| 19 | + |
| 20 | +`manifests-path` specifies the directory where the manifests should be written. |
| 21 | + |
| 22 | +`kustomize-dir` is a directory relative to the process's current working directory containing a `kustomization.yaml` which will be used to generate the manifests. |
| 23 | +The form of this `kustomization.yaml` is expected to be common across all providers. |
| 24 | +An example of the common parts is given below. |
| 25 | + |
| 26 | +`name` and `platform` are written as metadata. This metadata is used by the installer to determine which manifests to install. |
| 27 | + |
| 28 | +`attribute`s are purely informational, and do not affect the function of CAPI operator. |
| 29 | +In the future they may be used to enhance discoverability of what is being installed, e.g. including a component version in a user-visible revision phase name, but they will never affect behaviour. |
| 30 | + |
| 31 | +`self-image-ref` is the image reference of the provider image as referenced in the generated manifests. |
| 32 | +The installer will substitute this reference with the actual release image during installation. |
| 33 | +This must use the `registry.ci.openshift.org` registry. |
| 34 | +`manifests-gen` will return an error if it detects any image reference which does not use `registry.ci.openshift.org`. |
| 35 | + |
| 36 | +`protect-cluster-resource` indicates the name of the infrastructure cluster resource type which the CAPI operator will create for this provider. |
| 37 | +`manifests-gen` will generate a VAP for this resource to ensure that it cannot be modified. |
| 38 | + |
| 39 | +Each provider is expected to define a `kustomization.yaml` with a form similar to: |
| 40 | + |
| 41 | +```yaml |
| 42 | +apiVersion: kustomize.config.k8s.io/v1beta1 |
| 43 | +kind: Kustomization |
| 44 | + |
| 45 | +components: |
| 46 | +- tools/vendor/github.com/openshift/cluster-capi-operator/manifests-gen |
| 47 | + |
| 48 | +resources: |
| 49 | +- ../config/default |
| 50 | + |
| 51 | +images: |
| 52 | +- name: gcr.io/k8s-staging-cluster-api-aws/cluster-api-aws-controller |
| 53 | + newName: registry.ci.openshift.org/openshift |
| 54 | + newTag: aws-cluster-api-controllers |
| 55 | +``` |
| 56 | +
|
| 57 | +It must include the kustomize `Component` provided in the `manifests-gen` go module. |
| 58 | +If the `tools` module uses vendoring, this can be included directly as shown above. |
| 59 | +If the `tools` module does not use vendoring, this will have to be dynamically substituted with the location of the `manifests-gen` go module using an appropriate invocation of `go list`. |
| 60 | + |
| 61 | +Assuming the upstream provider uses the typical `kubebuilder` scaffolding, it should include `config/default` from the upstream repo as the base resource. |
| 62 | + |
| 63 | +Whatever value the upstream manifests use as the default image reference should be substituted with a new image reference in `registry.ci.openshift.org`. |
| 64 | + |
| 65 | +If a provider requires any provider-specific modifications to the upstream manifests, they should also be included in this `kustomization.yaml`. |
| 66 | +The standard modifications made by `manifests-gen` are detailed below. |
| 67 | + |
| 68 | +### Standard modifications made by manifests-gen |
| 69 | + |
| 70 | +`manifests-gen` makes the following set of modifications to provider manifests automatically. |
| 71 | + |
| 72 | +* Set the namespace of all namespaced objects to `openshift-cluster-api` |
| 73 | +* Replace cert-manager with OpenShift Service CA: |
| 74 | + Upstream CAPI providers typically include `cert-manager` metadata and manifests for webhooks. |
| 75 | + `manifests-gen` will automatically translate `cert-manager` manifests and metadata to use OpenShift Service CA instead. |
| 76 | +* Exclude `Namespace` and `Secret` objects from the manifests: we expect these to be created by other means. |
| 77 | +* The following set of changes to all Deployments: |
| 78 | + * Set the following annotations: |
| 79 | + * `target.workload.openshift.io/management: {"effect": "PreferredDuringScheduling"}`. |
| 80 | + * `openshift.io/required-scc: "restricted-v2"` |
| 81 | + * Set resource requests of all containers to `cpu: 10m` and `memory: 50Mi`. |
| 82 | + * Remove resource limits from all containers. |
| 83 | + * Set the terminationMessagePolicy of all containers to `FallbackToLogsOnError`. |
| 84 | + * Set priorityClassName of all pods to `sytem-cluster-critical` |
0 commit comments