From 3c4c154aeffa50f2c9e5bd4da92f357c134dd213 Mon Sep 17 00:00:00 2001 From: Andrew Taylor Date: Wed, 8 Jun 2022 13:23:01 -0400 Subject: [PATCH] OSDOCS-2933 - Java Operator structure peer review feedback applied --- _topic_maps/_topic_map.yml | 9 +++ modules/osdk-common-prereqs.adoc | 30 ++++++++ modules/osdk-quickstart.adoc | 32 +++++++++ operators/operator_sdk/java/_attributes | 1 + operators/operator_sdk/java/images | 1 + operators/operator_sdk/java/modules | 1 + .../java/osdk-java-project-layout.adoc | 13 ++++ .../java/osdk-java-quickstart.adoc | 19 +++++ .../operator_sdk/java/osdk-java-tutorial.adoc | 69 +++++++++++++++++++ operators/operator_sdk/java/snippets | 1 + 10 files changed, 176 insertions(+) create mode 120000 operators/operator_sdk/java/_attributes create mode 120000 operators/operator_sdk/java/images create mode 120000 operators/operator_sdk/java/modules create mode 100644 operators/operator_sdk/java/osdk-java-project-layout.adoc create mode 100644 operators/operator_sdk/java/osdk-java-quickstart.adoc create mode 100644 operators/operator_sdk/java/osdk-java-tutorial.adoc create mode 120000 operators/operator_sdk/java/snippets diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 3448a11b88..aea7d05404 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -1478,6 +1478,15 @@ Topics: File: osdk-helm-support - Name: Hybrid Helm Operator File: osdk-hybrid-helm + - Name: Java-based Operators + Dir: java + Topics: + - Name: Getting started + File: osdk-java-quickstart + - Name: Tutorial + File: osdk-java-tutorial + - Name: Project layout + File: osdk-java-project-layout - Name: Defining cluster service versions (CSVs) File: osdk-generating-csvs - Name: Working with bundle images diff --git a/modules/osdk-common-prereqs.adoc b/modules/osdk-common-prereqs.adoc index d2c8198720..dc748fbd6a 100644 --- a/modules/osdk-common-prereqs.adoc +++ b/modules/osdk-common-prereqs.adoc @@ -8,6 +8,8 @@ // * operators/operator_sdk/helm/osdk-helm-tutorial.adoc // * operators/operator_sdk/helm/osdk-hybrid-helm.adoc // * operators/operator_sdk/osdk-working-bundle-images.adoc +// * operators/operator_sdk/java/osdk-java-quickstart.adoc +// * operators/operator_sdk/java/osdk-java-tutorial.adoc ifeval::["{context}" == "osdk-ansible-quickstart"] :ansible: @@ -15,6 +17,18 @@ endif::[] ifeval::["{context}" == "osdk-ansible-tutorial"] :ansible: endif::[] +ifeval::["{context}" == "osdk-golang-quickstart"] +:golang: +endif::[] +ifeval::["{context}" == "osdk-golang-tutorial"] +:golang: +endif::[] +ifeval::["{context}" == "osdk-java-quickstart"] +:java: +endif::[] +ifeval::["{context}" == "osdk-java-tutorial"] +:java: +endif::[] [id="osdk-common-prereqs_{context}"] = Prerequisites @@ -31,6 +45,10 @@ ifdef::ansible[] - link:https://github.com/ansible/ansible-runner-http[Ansible Runner HTTP Event Emitter plug-in] v1.0.0+ - link:https://pypi.org/project/openshift/[OpenShift Python client] v0.11.2+ endif::[] +ifdef::java[] +- link:https://java.com/en/download/help/download_options.html[Java] v11+ +- link:https://maven.apache.org/install.html[Maven] v3.6.3+ +endif::[] - Logged into an {product-title} {product-version} cluster with `oc` with an account that has `cluster-admin` permissions - To allow the cluster to pull the image, the repository where you push your image must be set as public, or you must configure an image pull secret @@ -40,3 +58,15 @@ endif::[] ifeval::["{context}" == "osdk-ansible-tutorial"] :!ansible: endif::[] +ifeval::["{context}" == "osdk-golang-quickstart"] +:!golang: +endif::[] +ifeval::["{context}" == "osdk-golang-tutorial"] +:!golang: +endif::[] +ifeval::["{context}" == "osdk-java-quickstart"] +:!java: +endif::[] +ifeval::["{context}" == "osdk-java-tutorial"] +:!java: +endif::[] diff --git a/modules/osdk-quickstart.adoc b/modules/osdk-quickstart.adoc index 058d0f030b..362c2f11f1 100644 --- a/modules/osdk-quickstart.adoc +++ b/modules/osdk-quickstart.adoc @@ -25,6 +25,13 @@ ifeval::["{context}" == "osdk-helm-quickstart"] :app: nginx :group: demo endif::[] +ifeval::["{context}" == "osdk-java-quickstart"] +:java: +:type: Java +:app-proper: Memcached +:app: memcached +:group: cache +endif::[] :_content-type: PROCEDURE [id="osdk-quickstart_{context}"] @@ -57,6 +64,9 @@ endif::[] ifdef::helm[] with the `helm` plug-in endif::[] +ifdef::java[] +with the `quarkus` plug-in +endif::[] to initialize the project: + [source,terminal,subs="attributes+"] @@ -82,6 +92,13 @@ $ operator-sdk init \ --plugins=helm ---- endif::[] +ifdef::java[] +---- +$ operator-sdk init \ + --plugins=quarkus \ + --domain=example.com +---- +endif::[] . *Create an API.* + @@ -118,6 +135,15 @@ $ operator-sdk create api \ + This API uses the built-in Helm chart boilerplate from the `helm create` command. endif::[] +ifdef::java[] +---- +$ operator-sdk create api \ + --plugins quarkus \ + --group {group} \ + --version v1 \ + --kind {app-proper} +---- +endif::[] . *Build and push the Operator image.* + @@ -215,3 +241,9 @@ ifeval::["{context}" == "osdk-helm-quickstart"] :!app-proper: :!app: endif::[] +ifeval::["{context}" == "osdk-java-quickstart"] +:!java: +:!type: +:!app-proper: +:!app: +endif::[] diff --git a/operators/operator_sdk/java/_attributes b/operators/operator_sdk/java/_attributes new file mode 120000 index 0000000000..bf7c2529fd --- /dev/null +++ b/operators/operator_sdk/java/_attributes @@ -0,0 +1 @@ +../../../_attributes/ \ No newline at end of file diff --git a/operators/operator_sdk/java/images b/operators/operator_sdk/java/images new file mode 120000 index 0000000000..4399cbb3c0 --- /dev/null +++ b/operators/operator_sdk/java/images @@ -0,0 +1 @@ +../../../images/ \ No newline at end of file diff --git a/operators/operator_sdk/java/modules b/operators/operator_sdk/java/modules new file mode 120000 index 0000000000..7e8b50bee7 --- /dev/null +++ b/operators/operator_sdk/java/modules @@ -0,0 +1 @@ +../../../modules/ \ No newline at end of file diff --git a/operators/operator_sdk/java/osdk-java-project-layout.adoc b/operators/operator_sdk/java/osdk-java-project-layout.adoc new file mode 100644 index 0000000000..bb25548e65 --- /dev/null +++ b/operators/operator_sdk/java/osdk-java-project-layout.adoc @@ -0,0 +1,13 @@ +:_content-type: ASSEMBLY +[id="osdk-java-project-layout"] += Project layout for Java-based Operators +include::_attributes/common-attributes.adoc[] +:context: osdk-java-project-layout +:FeatureName: Java-based Operator SDK +include::snippets/technology-preview.adoc[] + +toc::[] + +The `operator-sdk` CLI can generate, or _scaffold_, a number of packages and files for each Operator project. + +// need to create the module ../osdk-java-project-layout.adoc[leveloffset=+1] diff --git a/operators/operator_sdk/java/osdk-java-quickstart.adoc b/operators/operator_sdk/java/osdk-java-quickstart.adoc new file mode 100644 index 0000000000..8edbf7a61b --- /dev/null +++ b/operators/operator_sdk/java/osdk-java-quickstart.adoc @@ -0,0 +1,19 @@ +:_content-type: ASSEMBLY +[id="osdk-java-quickstart"] += Getting started with Operator SDK for Java-based Operators +include::_attributes/common-attributes.adoc[] +:context: osdk-java-quickstart +:FeatureName: Java-based Operator SDK +include::snippets/technology-preview.adoc[] + +toc::[] + +To demonstrate the basics of setting up and running a Java-based Operator using tools and libraries provided by the Operator SDK, Operator developers can build an example Java-based Operator for Memcached, a distributed key-value store, and deploy it to a cluster. + +include::modules/osdk-common-prereqs.adoc[leveloffset=+1] +include::modules/osdk-quickstart.adoc[leveloffset=+1] + +[id="next-steps_osdk-java-quickstart"] +== Next steps + +* See xref:../../../operators/operator_sdk/java/osdk-java-tutorial.adoc#osdk-java-tutorial[Operator SDK tutorial for Java-based Operators] for a more in-depth walkthrough on building a Java-based Operator. diff --git a/operators/operator_sdk/java/osdk-java-tutorial.adoc b/operators/operator_sdk/java/osdk-java-tutorial.adoc new file mode 100644 index 0000000000..5819c5769f --- /dev/null +++ b/operators/operator_sdk/java/osdk-java-tutorial.adoc @@ -0,0 +1,69 @@ +:_content-type: ASSEMBLY +[id="osdk-java-tutorial"] += Operator SDK tutorial for Java-based Operators +include::_attributes/common-attributes.adoc[] +:context: osdk-java-tutorial +:FeatureName: Java-based Operator SDK +include::snippets/technology-preview.adoc[] + +toc::[] + +Operator developers can take advantage of Java programming language support in the Operator SDK to build an example Java-based Operator for Memcached, a distributed key-value store, and manage its lifecycle. + +This process is accomplished using two centerpieces of the Operator Framework: + +Operator SDK:: The `operator-sdk` CLI tool and `controller-runtime` library API + +Operator Lifecycle Manager (OLM):: Installation, upgrade, and role-based access control (RBAC) of Operators on a cluster + +[NOTE] +==== +This tutorial goes into greater detail than xref:../../../operators/operator_sdk/java/osdk-java-quickstart.adoc#osdk-java-quickstart[Getting started with Operator SDK for Java-based Operators]. +==== + +include::modules/osdk-common-prereqs.adoc[leveloffset=+1] + +// needs ifevals: +// include::modules/osdk-create-project.adoc[leveloffset=+1] +// include::modules/osdk-project-file.adoc[leveloffset=+2] + +// individual java modules go here +// +// include::modules/osdk-golang-manager.adoc[leveloffset=+2] +// include::modules/osdk-golang-multi-group-apis.adoc[leveloffset=+2] +// +// include::modules/osdk-golang-create-api-controller.adoc[leveloffset=+1] +// include::modules/osdk-golang-define-api.adoc[leveloffset=+2] +// include::modules/osdk-golang-generate-crd.adoc[leveloffset=+2] +// include::modules/osdk-about-openapi-validation.adoc[leveloffset=+3] +// +// include::modules/osdk-golang-implement-controller.adoc[leveloffset=+1] +// +// The next subsections explain how the controller in the example implementation watches resources and how the reconcile loop is triggered. You can skip these subsections to go directly to xref:../../../operators/operator_sdk/golang/osdk-golang-tutorial.adoc#osdk-run-operator_osdk-golang-tutorial[Running the Operator]. +// +// include::modules/osdk-golang-controller-resources.adoc[leveloffset=+2] +// include::modules/osdk-golang-controller-configs.adoc[leveloffset=+2] +// include::modules/osdk-golang-controller-reconcile-loop.adoc[leveloffset=+2] +// include::modules/osdk-golang-controller-rbac-markers.adoc[leveloffset=+2] + +// needs ifevals: +// include::modules/osdk-run-proxy.adoc[leveloffset=+1] +// include::modules/osdk-run-operator.adoc[leveloffset=+1] +// include::modules/osdk-run-locally.adoc[leveloffset=+2] +// include::modules/osdk-run-deployment.adoc[leveloffset=+2] + +[id="osdk-bundle-deploy-olm_{context}"] +=== Bundling an Operator and deploying with Operator Lifecycle Manager + +// need ifevals: +// include::modules/osdk-bundle-operator.adoc[leveloffset=+3] +// include::modules/osdk-deploy-olm.adoc[leveloffset=+3] +// +// include::modules/osdk-create-cr.adoc[leveloffset=+1] + +[role="_additional-resources"] +[id="additional-resources_osdk-java-tutorial"] +== Additional resources + +- See xref:../../../operators/operator_sdk/java/osdk-java-project-layout.adoc#osdk-java-project-layout[Project layout for Java-based Operators] to learn about the directory structures created by the Operator SDK. +- If a xref:../../../networking/enable-cluster-wide-proxy.adoc#enable-cluster-wide-proxy[cluster-wide egress proxy is configured], cluster administrators can xref:../../../operators/admin/olm-configuring-proxy-support.adoc#olm-configuring-proxy-support[override the proxy settings or inject a custom CA certificate] for specific Operators running on Operator Lifecycle Manager (OLM). diff --git a/operators/operator_sdk/java/snippets b/operators/operator_sdk/java/snippets new file mode 120000 index 0000000000..ce62fd7c41 --- /dev/null +++ b/operators/operator_sdk/java/snippets @@ -0,0 +1 @@ +../../../snippets/ \ No newline at end of file