Skip to content

Commit e2e9852

Browse files
michaelryanpetermichaelryanpeter
authored
Merge pull request #47613 from michaelryanpeter/osdocs-3429--osdk-2129_bundle-validations-good-practices
OSDOCS-3429: OSDK-2129 Bundle validations for Operators
2 parents 4e05ec6 + 00c50a0 commit e2e9852

File tree

5 files changed

+185
-0
lines changed

5 files changed

+185
-0
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1541,6 +1541,8 @@ Topics:
15411541
File: osdk-working-bundle-images
15421542
- Name: Validating Operators using the scorecard
15431543
File: osdk-scorecard
1544+
- Name: Validating Operator bundles
1545+
File: osdk-bundle-validate
15441546
- Name: High-availability or single-node cluster detection and support
15451547
File: osdk-ha-sno
15461548
- Name: Configuring built-in monitoring with Prometheus

‎modules/osdk-bundle-validate-about.adoc

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-bundle-validate.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="osdk-about-bundle-validate_{context}"]
7+
= About the bundle validate command
8+
9+
While the Operator SDK `scorecard` command can run tests on your Operator based on a configuration file and test images, the `bundle validate` subcommand can validate local bundle directories and remote bundle images for content and structure.
10+
11+
.`bundle validate` command syntax
12+
[source,terminal]
13+
----
14+
$ operator-sdk bundle validate <bundle_dir_or_image> <flags>
15+
----
16+
17+
[NOTE]
18+
====
19+
The `bundle validate` command runs automatically when you build your bundle using the the `make bundle` command.
20+
====
21+
22+
Bundle images are pulled from a remote registry and built locally before they are validated. Local bundle directories must contain Operator metadata and manifests. The bundle metadata and manifests must have a structure similar to the following bundle layout:
23+
24+
.Example bundle layout
25+
[source,terminal]
26+
----
27+
./bundle
28+
├── manifests
29+
│   ├── cache.my.domain_memcacheds.yaml
30+
│   └── memcached-operator.clusterserviceversion.yaml
31+
└── metadata
32+
└── annotations.yaml
33+
----
34+
35+
Bundle tests pass validation and finish with an exit code of `0` if no errors are detected.
36+
37+
.Example output
38+
[source,terminal]
39+
----
40+
INFO[0000] All validation tests have completed successfully
41+
----
42+
43+
Tests fail validation and finish with an exit code of `1` if errors are detected.
44+
45+
.Example output
46+
[source,terminal]
47+
----
48+
ERRO[0000] Error: Value cache.example.com/v1alpha1, Kind=Memcached: CRD "cache.example.com/v1alpha1, Kind=Memcached" is present in bundle "" but not defined in CSV
49+
----
50+
51+
Bundle tests that result in warnings can still pass validation with an exit code of `0` as long as no errors are detected. Tests only fail on errors.
52+
53+
.Example output
54+
[source,terminal]
55+
----
56+
WARN[0000] Warning: Value : (memcached-operator.v0.0.1) annotations not found
57+
INFO[0000] All validation tests have completed successfully
58+
----
59+
60+
For further information about the `bundle validate` subcommand, run:
61+
62+
[source,terminal]
63+
----
64+
$ operator-sdk bundle validate -h
65+
----

‎modules/osdk-bundle-validate-run.adoc

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-bundle-validate.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="osdk-bundle-validate-run_{context}"]
7+
= Running the bundle validate command
8+
9+
The default validator runs a test every time you enter the `bundle validate` command. You can run optional validators using the `--select-optional` flag. Optional validators run tests in addition to the default test.
10+
11+
.Prerequisites
12+
13+
* Operator project generated by using the Operator SDK
14+
15+
.Procedure
16+
17+
. If you want to run the default validator against a local bundle directory, enter the following command from your Operator project directory:
18+
+
19+
[source,terminal]
20+
----
21+
$ operator-sdk bundle validate ./bundle
22+
----
23+
24+
. If you want to run the default validator against a remote Operator bundle image, enter the following command:
25+
+
26+
[source,terminal]
27+
----
28+
$ operator-sdk bundle validate \
29+
<bundle_registry>/<bundle_image_name>:<tag>
30+
----
31+
+
32+
where:
33+
34+
<bundle_registry>:: Specifies the registry where the bundle is hosted, such as `quay.io/example`.
35+
<bundle_image_name>:: Specifies the name of the bundle image, such as `memcached-operator`.
36+
<tag>:: Specifies the tag of the bundle image, such as `v1.22.0`.
37+
+
38+
[NOTE]
39+
====
40+
If you want to validate an Operator bundle image, you must host your image in a remote registry. The Operator SDK pulls the image and builds it locally before running tests. The `bundle validate` command does not support testing local bundle images.
41+
====
42+
43+
. If you want to run an additional validator against an Operator bundle, enter the following command:
44+
+
45+
[source,terminal]
46+
----
47+
$ operator-sdk bundle validate \
48+
<bundle_dir_or_image> \
49+
--select-optional <test_label>
50+
----
51+
+
52+
where:
53+
54+
<bundle_dir_or_image>:: Specifies the local bundle directory or remote bundle image, such as `~/projects/memcached` or `quay.io/example/memcached-operator:v1.22`.
55+
<test_label>:: Specifies the name of the validator you want to run, such as `name=good-practices`.
56+
+
57+
.Example output
58+
[source,terminal]
59+
----
60+
ERRO[0000] Error: Value apiextensions.k8s.io/v1, Kind=CustomResource: unsupported media type registry+v1 for bundle object
61+
WARN[0000] Warning: Value k8sevent.v0.0.1: owned CRD "k8sevents.k8s.k8sevent.com" has an empty description
62+
----

‎modules/osdk-bundle-validate-tests.adoc

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * operators/operator_sdk/osdk-bundle-validate.adoc
4+
5+
:_content-type: REFERENCE
6+
[id="osdk-bundle-validate-tests_{context}"]
7+
= Built-in bundle validate tests
8+
9+
The Operator SDK ships with pre-defined validators arranged into suites. If you run the `bundle validate` command without specifying a validator, the default test runs. The default test verifies that a bundle adheres to the specifications defined by the Operator Framework community. For more information, see "Bundle format".
10+
11+
You can run optional validators to test for issues such as OperatorHub compatibility or deprecated Kubernetes APIs. Optional validators always run in addition to the default test.
12+
13+
.`bundle validate` command syntax for optional test suites
14+
[source,terminal]
15+
----
16+
$ operator-sdk bundle validate <bundle_dir_or_image>
17+
--select-optional <test_label>
18+
----
19+
20+
[id="osdk-bundle-validate-additional-tests_{context}"]
21+
.Addtional `bundle validate` validators
22+
[cols="3,7,3",options="header"]
23+
|===
24+
|Name |Description |Label
25+
26+
|Operator Framework
27+
|This validator tests an Operator bundle against the entire suite of validators provided by the Operator Framework.
28+
|`suite=operatorframework`
29+
30+
|OperatorHub
31+
|This validator tests an Operator bundle for compatibility with OperatorHub.
32+
|`name=operatorhub`
33+
34+
|Good Practices
35+
|This validator tests whether an Operator bundle complies with good practices as defined by the Operator Framework. It checks for issues, such as an empty CRD description or unsupported Operator Lifecycle Manager (OLM) resources.
36+
|`name=good-practices`
37+
|===

‎operators/operator_sdk/osdk-bundle-validate.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
:_content-type: ASSEMBLY
2+
[id="osdk-bundle-validate"]
3+
= Validating Operator bundles
4+
include::_attributes/common-attributes.adoc[]
5+
:context: osdk-bundle-validate
6+
7+
toc::[]
8+
9+
As an Operator author, you can run the `bundle validate` command in the Operator SDK to validate the content and format of an Operator bundle. You can run the command on a remote Operator bundle image or a local Operator bundle directory.
10+
11+
include::modules/osdk-bundle-validate-about.adoc[leveloffset=+1]
12+
include::modules/osdk-bundle-validate-tests.adoc[leveloffset=+1]
13+
14+
[role="_additional-resources"]
15+
.Additional resources
16+
17+
* xref:../../operators/understanding/olm-packaging-format.adoc#olm-bundle-format_olm-packaging-format[Bundle format]
18+
19+
include::modules/osdk-bundle-validate-run.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)