diff --git a/assemblies/assembly-rhdh-operator-flavors.adoc b/assemblies/assembly-rhdh-operator-flavors.adoc new file mode 100644 index 0000000000..ddad8084a6 --- /dev/null +++ b/assemblies/assembly-rhdh-operator-flavors.adoc @@ -0,0 +1,13 @@ +:_mod-docs-content-type: ASSEMBLY +:context: assembly-operator-flavors +[id="{context}"] += {product} Operator Flavors + +// about operator flavors +include::modules/installation/con-install-operator-flavors.adoc[leveloffset=+1] + +include::modules/installation/proc-install-create-custom-flavor.adoc[leveloffset=+1] + +include::modules/installation/proc-install-distribute-custom-flavor.adoc[leveloffset=+1] + +include::modules/installation/ref-install-flavor-schema.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/installation/con-install-operator-flavors.adoc b/modules/installation/con-install-operator-flavors.adoc new file mode 100644 index 0000000000..d90cb6d416 --- /dev/null +++ b/modules/installation/con-install-operator-flavors.adoc @@ -0,0 +1,31 @@ +[id='con-install-operator-flavors_{context}'] += Flavor framework architecture + +The flavor framework for the {product} ({product-very-short}) Operator is an extension of the existing Configuration Profiles mechanism. A flavor is a specialized profile that goes beyond simple configuration to encompass a complete, opinionated {product-very-short} installation. The architecture is designed to be flexible and modular, allowing for the creation of turnkey solutions. + +The core of the framework is its reliance on Kustomize, a tool used by the operator to manage and apply Kubernetes manifests. Flavors act as Kustomize overlays, which means they can modify and extend a base {product-very-short} deployment with specific configurations, resources, and dependencies. + +A complete flavor is defined by a standardized set of directories and files: + +Flavor Manifest:: A `kustomization.yaml` file that acts as the central definition for the flavor, orchestrating how all the other components are applied. + +Configuration Directory (`config/`):: Contains {product-very-short} application and plugin configuration files. + +Resources Directory (`resources/`):: Holds additional Kubernetes resources that need to be deployed, such as custom resource definitions (CRDs), catalog entities, and templates. + +Hooks Directory (`hooks/`):: Stores manifests for pre-installation and post-installation tasks, which are executed as Kubernetes jobs. + += Flavor framework implementation +The implementation of the flavor framework is handled by the {product-very-short} Operator itself, which is extended to recognize and process the `spec.flavor` field in the Backstage custom resource (CR). + +The implementation details include: + +Flavor selection:: The Backstage CR is extended to include a `spec.flavor` field, allowing users to select a predefined or custom flavor. + +Operator integration:: When a Backstage CR is applied, the operator checks for the specified flavor. It then uses Kustomize to process the flavor's manifest and apply its configurations, resources, and hooks to the cluster. + +Dependency management:: The Operator is responsible for automatically checking for and deploying any required infrastructure dependencies (for example, other operators or CRDs) that a flavor's plugins may need. It validates these requirements before applying the flavor's configuration. + +Hooks execution:: The Operator handles the lifecycle of pre-installation and post-installation hooks. It monitors the status of the Kubernetes jobs created by these hooks and adjusts the deployment process accordingly. + +Distribution:: Flavors can be shipped with the Operator or distributed externally as container images. When a user specifies an external flavor image, the Operator pulls the image, extracts the flavor's files, and applies them in the same way as a built-in flavor. This container-based approach provides a consistent and secure way to manage custom flavors. \ No newline at end of file diff --git a/modules/installation/proc-install-create-custom-flavor.adoc b/modules/installation/proc-install-create-custom-flavor.adoc new file mode 100644 index 0000000000..294e8ff35a --- /dev/null +++ b/modules/installation/proc-install-create-custom-flavor.adoc @@ -0,0 +1,43 @@ +[id='proc-install-create-custom-flavor_{context}'] += Creating a custom flavor +A custom flavor is a new operator profile with a specific directory structure. You can create a new flavor by following these steps: + +.Procedure + +. Create a dedicated directory for your flavor, following a standardized structure. This structure helps the operator identify and process all the components of your flavor: ++ +[source,terminal,subs="+quotes"] +---- +flavors/ +└── my-custom-flavor/ + ├── kustomize.yaml + ├── config/ + │   ├── app-config.yaml + │   └── plugins/ + │   └── my-plugin.yaml + ├── resources/ + │   ├── dependencies.yaml + │   └── catalog/ + │   └── entities.yaml + └── hooks/ + ├── pre-install/ + │   └── job.yaml + └── post-install/ + └── job.yaml +---- ++ +where + +_kustomize.yaml_:: This is your flavor's manifest file that acts as the central definition, orchestrating the application of all other files in the directory. + +_config/_:: Contains the core app-config.yaml for Red Hat Developer Hub, along with any plugin-specific configuration files. + +_resources/_:: Holds additional Kubernetes resources your flavor needs. This can include CRDs for dependencies or initial catalog entities to populate {product-very-short}. + +_hooks/_:: Contains manifests for Kubernetes jobs that run before (pre-install) or after (post-install) the RHDH instance is deployed. + +. (Optional) If your flavor uses dynamic plugins that require specific Kubernetes resources, define these resources as YAML manifests in your `config/profile/{PROFILE}/plugin-deps` directory. + +. (Optional) For dependencies that require operators or other infrastructure, specify them in the _plugin-infra_ directory. + +. (Optional) Write Kubernetes job manifests for any pre-installation or post-installation tasks. The Operator will execute these jobs and monitor their status. \ No newline at end of file diff --git a/modules/installation/proc-install-distribute-custom-flavor.adoc b/modules/installation/proc-install-distribute-custom-flavor.adoc new file mode 100644 index 0000000000..386d4a96ba --- /dev/null +++ b/modules/installation/proc-install-distribute-custom-flavor.adoc @@ -0,0 +1,37 @@ +[id='proc-install-distribute-custom-flavor_{context}'] += Distributing a custom flavor +Custom flavors can be distributed as container images, offering a secure and versioned approach. + +.Procedure + +. Create a container image that contains your flavor's directory structure at a specific location, typically `/flavor/`. The image should be lightweight and contain only the necessary manifests and files. ++ +[source,terminal,subs="+quotes"] +---- +/flavor/ +├── flavor.yaml # Flavor manifest +├── config/ +├── resources/ +└── hooks/ +---- + +. When the image is built, push it to a container registry which makes the flavor accessible to others, for example: ++ +[source,terminal,subs="+quotes"] +---- +podman push quay.io/myorg/my-custom-flavor:1.0.0 +---- + +. Users can deploy your custom flavor by referencing the container image directly in their Backstage custom resource. The operator pulls the image, extracts the contents, and applies the configuration automatically. For example: ++ +[source,yaml,subs="+attributes"] +---- +apiVersion: backstage.redhat.com/v1alpha1 +kind: Backstage +metadata: + name: custom-hub +spec: + flavor: + name: my-custom-flavor + image: quay.io/myorg/my-custom-flavor:1.0.0 +---- \ No newline at end of file diff --git a/modules/installation/ref-install-flavor-schema.adoc b/modules/installation/ref-install-flavor-schema.adoc new file mode 100644 index 0000000000..8a2c1dacdd --- /dev/null +++ b/modules/installation/ref-install-flavor-schema.adoc @@ -0,0 +1,34 @@ +[id='ref-install-flavor-schema_{context}'] += Flavor manifest schema +The flavor manifest is a `kustomization.yaml` file that serves as the central definition for a flavor. This file is used by the {product-very-short} Operator to orchestrate the deployment of all other components. The manifest schema leverages standard Kustomize fields and is typically structured as follows: + +[source,yaml,subs="+attributes"] +---- +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: + - config/ + - resources/ + - hooks/ +---- + +_apiVersion_ and _kind_:: These are standard Kustomize fields that define the schema version and type. + +_resources_:: This field is a list that points to the directories containing the flavor's configuration files, Kubernetes resources, and hooks. The Operator uses this list to process and apply all the components within the flavor. + +== Configuration options +A flavor's configuration is managed through the directories and files referenced in its manifest. The primary configuration options are: + +{product-very-short} application configuration:: The _config/app-config.yaml_ file contains the core configuration for the {product-very-short} instance. This can include settings for the backend, authentication providers, and other core functionalities. + +Dynamic plugins configuration:: Files located in the _config/plugins/_ directory define the settings for specific dynamic plugins. This includes enabling or disabling plugins and configuring their unique properties. + +Kubernetes resources:: The _resources/_ directory contains standard Kubernetes manifests. This can include: ++ +* Dependency manifests that define Custom Resource Definitions (CRDs) for external services. + +* Catalog entities which are YAML files for initial catalog entries, such as templates, components, and APIs. + +Hooks:: The _hooks/_ directory contains manifests for Kubernetes jobs. These jobs can be used to perform pre-installation or post-installation tasks, such as creating secrets or running data migrations. + +Platform-Specific Overrides:: Flavors can include platform-specific patches. Files with a _.k8s_ or _.ocp_ extension for example, _app-config.yaml.ocp_ provide overrides for vanilla Kubernetes and OpenShift environments, respectively. The operator automatically applies the correct patch based on the cluster's platform. \ No newline at end of file diff --git a/modules/release-notes/ref-release-notes-developer-preview.adoc b/modules/release-notes/ref-release-notes-developer-preview.adoc new file mode 100644 index 0000000000..bf2fd4f53d --- /dev/null +++ b/modules/release-notes/ref-release-notes-developer-preview.adoc @@ -0,0 +1,16 @@ +:_content-type: REFERENCE +[id="developer-preview"] += Developer Preview + +This section lists Developer Preview features in {product} {product-version}. + +[IMPORTANT] +==== +Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA. + +For more information about the support scope of Red Hat Developer Preview features, see link:https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope]. +==== + + +None. + diff --git a/titles/operator-flavors/artifacts b/titles/operator-flavors/artifacts new file mode 120000 index 0000000000..f30b6dea60 --- /dev/null +++ b/titles/operator-flavors/artifacts @@ -0,0 +1 @@ +../../artifacts \ No newline at end of file diff --git a/titles/operator-flavors/assemblies b/titles/operator-flavors/assemblies new file mode 120000 index 0000000000..91646274db --- /dev/null +++ b/titles/operator-flavors/assemblies @@ -0,0 +1 @@ +../../assemblies \ No newline at end of file diff --git a/titles/operator-flavors/docinfo.xml b/titles/operator-flavors/docinfo.xml new file mode 100644 index 0000000000..bb418e8b0a --- /dev/null +++ b/titles/operator-flavors/docinfo.xml @@ -0,0 +1,12 @@ +TechDocs for {product} +{product} +{product-version} +The Red Hat Developer Hub (RHDH) Operator Flavors feature provides a structured framework for deploying opinionated, pre-configured installations of RHDH tailored to specific use cases + + The Red Hat Developer Hub (RHDH) Operator Flavors feature provides a structured framework for deploying opinionated, pre-configured installations of RHDH tailored to specific use cases. This design builds upon the existing Operator Profiles framework to enable turnkey solutions that avoid the "blank page" experience of an empty RHDH installation. Flavors allow teams to quickly deploy RHDH instances optimized for their specific needs. + + + {company-name} Customer Content Services + + diff --git a/titles/operator-flavors/images b/titles/operator-flavors/images new file mode 120000 index 0000000000..5fa6987088 --- /dev/null +++ b/titles/operator-flavors/images @@ -0,0 +1 @@ +../../images \ No newline at end of file diff --git a/titles/operator-flavors/master.adoc b/titles/operator-flavors/master.adoc new file mode 100644 index 0000000000..00203a7746 --- /dev/null +++ b/titles/operator-flavors/master.adoc @@ -0,0 +1,8 @@ +include::artifacts/attributes.adoc[] + +:context: operator-flavors +[id="{context}"] += Operator flavors for {product} + +//Dynamic plugins +include::assemblies/assembly-rhdh-operator-flavors.adoc[leveloffset=+1] diff --git a/titles/operator-flavors/modules b/titles/operator-flavors/modules new file mode 120000 index 0000000000..8b0e854007 --- /dev/null +++ b/titles/operator-flavors/modules @@ -0,0 +1 @@ +../../modules \ No newline at end of file