diff --git a/.github/workflows/sanity.yaml b/.github/workflows/sanity.yaml index 442d0547..c3a0faf7 100644 --- a/.github/workflows/sanity.yaml +++ b/.github/workflows/sanity.yaml @@ -21,7 +21,15 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - - name: Run linting checks + - name: Run golangci linting checks uses: "golangci/golangci-lint-action@v2" with: version: "v1.45.2" + + - name: Lint markdown files + uses: github/super-linter/slim@v4 + env: + VALIDATE_ALL_CODEBASE: true + DEFAULT_BRANCH: main + # only runs the markdown linter + VALIDATE_MARKDOWN: true diff --git a/README.md b/README.md index dc01c82f..a38abddd 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,7 @@ +# RukPak [![License](http://img.shields.io/:license-apache-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0.html) [![Slack Channel](https://img.shields.io/badge/chat-4A154B?logo=slack&logoColor=white "Slack Channel")](https://kubernetes.slack.com/archives/C038B7MF75M) -# RukPak - RukPak runs in a Kubernetes cluster and defines an API for installing cloud native bundle content. ## Introduction @@ -48,7 +47,7 @@ the release notes on how to install a particular release. The only requirement i that is configured to target the cluster to install to. > Note: RukPak depends on [cert-manager](https://cert-manager.io/) for creating and managing certificates for its webhooks. -> cert-manager should be installed prior to installing RukPak. See the cert-manager [installation docs](https://cert-manager.io/docs/installation/) +> cert-manager should be installed prior to installing RukPak. See the cert-manager [installation docs](https://cert-manager.io/docs/installation/) > for more information on how to install cert-manager. It is recommended to install the latest release to access the latest features and new bugfixes. RukPak releases target diff --git a/cmd/crdvalidator/README.md b/cmd/crdvalidator/README.md index 1463fba5..90a20773 100644 --- a/cmd/crdvalidator/README.md +++ b/cmd/crdvalidator/README.md @@ -1,11 +1,18 @@ # crdvalidator ## Summary -A part of the core value proposition for RukPak is the safe upgrade of a [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) (`CRD`). As a result, this repository comes equipped with a "CRD Validator Webhook" (`crdvalidator`), that will validate all `CRD` upgrades created by RukPak. This protects your `BundleInstance` pivots from having potentially dangerous effects such as data loss. + +A part of the core value proposition for RukPak is the safe upgrade of +a [CustomResourceDefinition](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/) (`CRD`) +. As a result, this repository comes equipped with a "CRD Validator Webhook" (`crdvalidator`), that will validate +all `CRD` upgrades created by RukPak. This protects your `BundleInstance` pivots from having potentially dangerous +effects such as data loss. ### How to use -`crdvalidator` will ensure that any `CRD` upgrade is safe as long as the CRD is associated with RukPak. If you would like to disable validation for a `CRD` included in a specific `Bundle`, you will need to explicitly set the `core.rukpak.io/safe-crd-upgrade-validation` annotation to `false` within that specific CRD's manifest. +`crdvalidator` will ensure that any `CRD` upgrade is safe as long as the CRD is associated with RukPak. If you would +like to disable validation for a `CRD` included in a specific `Bundle`, you will need to explicitly set +the `core.rukpak.io/safe-crd-upgrade-validation` annotation to `false` within that specific CRD's manifest. ```yaml apiVersion: apiextensions.k8s.io/v1 @@ -16,7 +23,10 @@ metadata: ``` ### What is protected -There are three main cases `crdvalidator` is checking against with every specified `CRD` upgrade. These are where a new `CRD`: + +There are three main cases `crdvalidator` is checking against with every specified `CRD` upgrade. These are where a +new `CRD`: + 1. Removes a stored version and ensures that removing the stored version does not result in data loss. 2. Changes a version that old `CRD` had and it must validate existing CRs against the new schema. 3. Adds a version that old `CRD` does not have. In this case `crdvalidator` checks if the conversion strategy is: @@ -24,7 +34,9 @@ There are three main cases `crdvalidator` is checking against with every specifi - Webhook, then allow update (assuming webhook handles conversion correctly) #### Update the schema that invalidates existing CRs -Say that you have installed a `CRD` onto the cluster with a Kind of `Sample` that has a single property of `examplearray`. + +Say that you have installed a `CRD` onto the cluster with a Kind of `Sample` that has a single property +of `examplearray`. ```yaml apiVersion: apiextensions.k8s.io/v1 @@ -39,23 +51,23 @@ metadata: # ... # spec: - versions: + versions: - name: v1alpha1 schema: openAPIV3Schema: - properties: - exampleProperty: - description: exampleProperty is a string property to demonstrate crd validation logic. - type: string + properties: + exampleProperty: + description: exampleProperty is a string property to demonstrate crd validation logic. + type: string ``` -With this installed onto the cluster, you go ahead and create a `CR` of a `Sample` onto the cluster. +With this installed onto the cluster, you go ahead and create a `CR` of a `Sample` onto the cluster. ```yaml apiVersion: sample.example.io kind: Sample metadata: - name: sampleResource + name: sampleResource ``` If you then update that `CRD`'s schema in such a way that the `CR` you just created was invalidated, like so: @@ -65,41 +77,45 @@ If you then update that `CRD`'s schema in such a way that the `CR` you just crea # ... # spec: - versions: + versions: - name: v1alpha1 schema: openAPIV3Schema: - type: string - required: # Updating the exampleProperty to be required - - exampleProperty - properties: - exampleProperty: - description: exampleProperty is an array of strings to demonstrate crd validation logic. - type: string + type: string + required: # Updating the exampleProperty to be required + - exampleProperty + properties: + exampleProperty: + description: exampleProperty is an array of strings to demonstrate crd validation logic. + type: string ``` +`crdvalidator` will prevent the update from occurring with the following error. This is because the existing `CR` does +not have a value set for the required field of `exampleProperty`. -`crdvalidator` will prevent the update from occurring with the following error. This is because the existing `CR` does not have a value set for the required field of `exampleProperty`. - -``` -admission webhook "webhook.crdvalidator.io" denied the request: failed to validate safety of UPDATE for CRD "sample.example.io" (NOTE: to disable this validation, set the "core.rukpak.io/safe-crd-upgrade-validation" annotation to "false"): error validating existing CRs against new CRD's schema for "sample.example.io": existing custom object /sampleResource failed validation for new schema version v1alpha1: [].exampleProperty: Required value +```text +admission webhook "webhook.crdvalidator.io" denied the request: failed to validate safety of UPDATE for CRD "sample.example.io" (NOTE: to disable this validation, set the "core.rukpak.io/safe-crd-upgrade-validation" annotation to "false"): +error validating existing CRs against new CRD's schema for "sample.example.io": existing custom object /sampleResource failed validation for new schema version v1alpha1: [].exampleProperty: Required value ``` ## Running locally -`crdvalidator` is included with every default installation of RukPak. To run this locally, simply run the make target with a kind cluster started. +`crdvalidator` is included with every default installation of RukPak. To run this locally, simply run the make target +with a kind cluster started. ```console make run ``` -By default, `crdvalidator`'s test suite runs alongside RukPak's, but you can also just run `crdvalidator`'s specific tests. +By default, `crdvalidator`'s test suite runs alongside RukPak's, but you can also just run `crdvalidator`'s specific +tests. ```console make e2e TEST="crdvalidator" ``` -If you would like to install the `crdvalidator` onto your current cluster without RukPak, you'll need to install `cert-mgr` and then `crdvalidator` +If you would like to install the `crdvalidator` onto your current cluster without RukPak, you'll need to +install `cert-mgr` and then `crdvalidator` ```console make cert-mgr install-crdvalidator-webhook