diff --git a/content/contribute/creating-a-pattern.adoc b/content/contribute/creating-a-pattern.adoc index 03c7e9a402..396aea7f86 100644 --- a/content/contribute/creating-a-pattern.adoc +++ b/content/contribute/creating-a-pattern.adoc @@ -32,9 +32,10 @@ Therefore the question really is: How do I move my successful architecture solut == Requirements for creating a new pattern -* The patterns framework requires some artifacts like OpenShift GitOps (ArgoCD) in order to provide the GitOps automation. All existing patterns use OpenShift GitOps as a starting point. The link:/patterns/multicloud-gitops[multicloud-gitops pattern] is the most fundamental of patterns and therefore it is recommended to use it as a base pattern. I.e Create a new pattern based on it. +* The recommended way to create a new pattern is to use link:/learn/creating-patterns-with-patternizer/[patternizer], which generates all required scaffolding automatically. Alternatively, fork the link:/patterns/multicloud-gitops[multicloud-gitops pattern] as a starting point. +* The patterns framework requires OpenShift GitOps (ArgoCD) to provide the GitOps automation. Patternizer sets this up for you; if starting from a fork, ensure OpenShift GitOps is included. * Create a new branch on your new pattern to perform the initial changes. -* Deploy the initial new pattern pattern to the cluster. +* Deploy the initial new pattern to the cluster. == Moving to the validated patterns framework diff --git a/content/learn/creating-patterns-with-patternizer.adoc b/content/learn/creating-patterns-with-patternizer.adoc new file mode 100644 index 0000000000..cb8e034743 --- /dev/null +++ b/content/learn/creating-patterns-with-patternizer.adoc @@ -0,0 +1,165 @@ +--- +menu: + learn: + parent: Patterns quick start +title: Creating a pattern with patternizer +weight: 19 +--- + +:toc: +:imagesdir: /images +:_content-type: ASSEMBLY +include::modules/comm-attributes.adoc[] + +== Creating a new pattern with patternizer + +link:https://github.com/validatedpatterns/patternizer[Patternizer] is a command-line tool that bootstraps a Git repository into a ready-to-use Validated Pattern. It generates all required scaffolding -- values files, Makefile, `pattern.sh`, and Ansible configuration -- so you can focus on defining your applications rather than wiring up framework boilerplate. + +=== Prerequisites + +* A container runtime (Podman or Docker) +* Git + +[TIP] +.Shell Function +==== +You can add a simple shell function to your shell configuration file (for example `~/.zshrc` or `~/.bashrc`) to enable easier use of the tool. + +[source,bash] +---- +pattern() { + podman run --pull=newer \ + -v "$PWD:$PWD:z" \ + -w "$PWD" \ + quay.io/validatedpatterns/patternizer "$@" +} +---- + +With this function, you can run `pattern init` directly instead of the full `podman run` command. The examples below assume this function is in place. +==== + +=== Step 1: Create your pattern repository + +Create or clone an empty Git repository named after your pattern. The directory name becomes the pattern name in `values-global.yaml`. + +[source,terminal] +---- +$ mkdir my-pattern && cd my-pattern +$ git init +---- + +=== Step 2: Initialize the pattern + +To create a pattern without the secrets framework: + +[source,terminal] +---- +$ pattern init +---- + +To create a pattern with HashiCorp Vault and External Secrets Operator scaffolding: + +[source,terminal] +---- +$ pattern init --with-secrets +---- + +==== What patternizer generates + +Running `pattern init --with-secrets` on an empty directory named `my-pattern` produces the following files: + +[source,bash] +---- +my-pattern +├── ansible.cfg # default Ansible configuration +├── Makefile # stub Makefile which includes Makefile-common +├── Makefile-common # common commands (install, load-secrets, etc.) +├── pattern.sh # convenience utility container (has oc, helm, make, etc.) +├── values-global.yaml # names the pattern based on the directory and sets common defaults +├── values-prod.yaml # contains the components for the secrets framework +└── values-secret.yaml.template # stub for the secrets file +---- + +The generated `values-global.yaml` contains: + +[source,yaml] +---- +global: + pattern: my-pattern + singleArgoCD: true + secretLoader: + disabled: false +main: + clusterGroupName: prod + multiSourceConfig: + enabled: true + clusterGroupChartVersion: 0.9.* +---- + +The generated `values-prod.yaml` contains: + +[source,yaml] +---- +clusterGroup: + name: prod + namespaces: + my-pattern: + vault: + external-secrets-operator: + operatorGroup: true + targetNamespaces: [] + external-secrets: + subscriptions: + eso: + name: openshift-external-secrets-operator + namespace: external-secrets-operator + channel: stable-v1 + applications: + openshift-external-secrets: + name: openshift-external-secrets + namespace: external-secrets + chart: openshift-external-secrets + chartVersion: 0.0.* + vault: + name: vault + namespace: vault + chart: hashicorp-vault + chartVersion: 0.1.* +---- + +If you omit `--with-secrets`, the generated files will not include the Vault and External Secrets Operator configuration, and `secretLoader.disabled` will be set to `true` in `values-global.yaml`. + +=== Step 3: Define your pattern content + +After initialization, you need to add your operators, applications, and Helm charts to the pattern. There are two approaches: + +==== Using the pattern-author AI coding skill + +Patternizer installs an AI coding skill to `.claude/skills/pattern-author/` and `.cursor/skills/pattern-author/` during initialization. This skill teaches AI coding assistants such as Claude Code and Cursor how to author Validated Patterns -- defining namespaces, operators, applications, secrets, hub/spoke clusters, and more. + +Open the initialized repository in your AI-assisted editor and the skill will be available automatically. You can ask the assistant to add operators, wire in Helm charts, configure secrets, or set up multi-cluster deployments. + +==== Manually editing values files + +You can directly edit the generated values files to define your pattern: + +* Add operator subscriptions and namespaces to `values-prod.yaml` +* Add Helm chart applications to `values-prod.yaml` +* Configure global settings in `values-global.yaml` +* Define secrets in `values-secret.yaml.template` + +For detailed guidance on structuring your pattern, see link:/learn/vp_structure_vp_pattern/[Structuring a validated pattern]. For adding operators, see link:/learn/vp_add_ops_to_pattern/[Adding operators to the framework]. + +[NOTE] +.Idempotency +==== +The `pattern init` command is idempotent and can be run multiple times during pattern creation to update the pattern values files. You can go from `pattern init` to `pattern init --with-secrets` to add the secrets framework to your pattern. If you use `helm create` (or `./pattern.sh helm create`) to create Helm charts and then run `pattern init` again, the Helm charts will be automatically added to your `values-prod.yaml`. +==== + +=== Next steps + +* Deploy an existing pattern like link:/learn/getting-started-multi-cloud-gitops/[Multicloud GitOps] to explore how the framework works in practice +* Learn about link:/learn/vp_structure_vp_pattern/[structuring a validated pattern] and best practices +* Add operators to your pattern with link:/learn/vp_add_ops_to_pattern/[Adding operators to the framework] +* Configure secrets with link:/learn/getting-started-secret-management/[Configuring secrets] +* Visit the link:https://github.com/validatedpatterns/patternizer[patternizer repository on GitHub] for the latest documentation diff --git a/content/learn/getting-started-multi-cloud-gitops.adoc b/content/learn/getting-started-multi-cloud-gitops.adoc index 1b58b90503..197d9c84c9 100644 --- a/content/learn/getting-started-multi-cloud-gitops.adoc +++ b/content/learn/getting-started-multi-cloud-gitops.adoc @@ -14,24 +14,19 @@ include::modules/comm-attributes.adoc[] == Getting Started with Multicloud GitOps -Multicloud GitOps is a foundational pattern that demonstrates GitOps principles for managing applications across multiple clusters. It provides: +Multicloud GitOps is a foundational pattern that demonstrates the core concepts of Validated Patterns in action. Deploying it is a great way to explore how the framework works before creating your own pattern with link:/learn/creating-patterns-with-patternizer/[patternizer]. It provides: * A GitOps framework using `ArgoCD` * Infrastructure-as-Code practices * Multi-cluster management capabilities -* Template for secure secret management +* Secure secret management with HashiCorp Vault -Red Hat recommend the Multicloud GitOps pattern as your base pattern because: +Deploying Multicloud GitOps gives you hands-on experience with: -. It establishes core GitOps practices -. Provides a minimal but complete implementation -. Serves as a foundation for other patterns -. Demonstrates key validated patterns concepts - -[NOTE] -==== -Other patterns build upon these concepts, making this an ideal starting point for your validated patterns journey. -==== +. How operators and applications are defined in values files +. How ArgoCD manages application lifecycle +. How secrets are loaded and managed +. How the pattern framework ties everything together == Deploying the Multicloud GitOps pattern diff --git a/content/learn/quickstart.adoc b/content/learn/quickstart.adoc index 40200ac33c..9d3deee598 100644 --- a/content/learn/quickstart.adoc +++ b/content/learn/quickstart.adoc @@ -2,7 +2,7 @@ layout: default title: Patterns quick start menu: learn -weight: 20 +weight: 18 --- :toc: @@ -11,17 +11,19 @@ include::modules/comm-attributes.adoc[] == Patterns quick start overview -This validated pattern quickstart offers a streamlined guide to deploying predefined, reliable configurations and applications, ensuring they meet established standards. It provides step-by-step instructions on setup, prerequisites, and configuration, enabling administrators to deploy tested, supportable patterns quickly. These patterns simplify complex deployments by applying reusable configurations suited to various infrastructure and application needs, allowing users to efficiently deploy, manage, and scale applications with GitOps. This approach also reduces the risks and time associated with custom configurations. +This quickstart helps you get up and running with Validated Patterns -- whether you are creating a new pattern or deploying an existing one. -Validated patterns can be deployed using either the OpenShift-based Validated Patterns framework or the Ansible GitOps Framework (AGOF). The OpenShift-based validated patterns framework is the most common method for deploying applications and infrastructure on the OpenShift Container Platform. It offers a set of predefined configurations and patterns that follow best practices and are validated by Red Hat. +* **link:/learn/creating-patterns-with-patternizer/[Create a new pattern]** -- Use patternizer to bootstrap a Git repository into a ready-to-use Validated Pattern with all required scaffolding. +* **link:/learn/getting-started-multi-cloud-gitops/[Deploy an existing pattern]** -- Deploy the Multicloud GitOps pattern to explore how the framework works in practice. -== Getting Started with Validated Patterns +Validated Patterns can be deployed using either the OpenShift-based Validated Patterns framework or the Ansible GitOps Framework (AGOF). The OpenShift-based Validated Patterns framework is the most common method for deploying applications and infrastructure on the OpenShift Container Platform. It offers a set of predefined configurations and patterns that follow best practices and are validated by Red Hat. -This guide steps you through the process of deploying your first validated pattern on an OpenShift cluster. By the end of this guide, you'll have a working instance of the Multicloud GitOps pattern, which serves as an excellent foundation for exploring other patterns. +== Getting Started with Validated Patterns === What You'll Learn -. Setting up prerequisites for validated patterns +. Setting up prerequisites for Validated Patterns +. Creating a new pattern with patternizer . Installing and configuring the Validated Patterns Operator . Deploying the Multicloud GitOps pattern . Managing secrets and configurations @@ -52,8 +54,7 @@ Before beginning, ensure you have the following: .For disconnected environments: * One or more openshift clusters deployed in a disconnected network -* An OCI-compliant registry that is accessible from the disconnected network +* An OCI-compliant registry that is accessible from the disconnected network * A Git Repository that is accessible from the disconnected network For more information on disconnected installation, see link:/learn/disconnected-installation/[Deploying in a disconnected network]. - diff --git a/content/learn/vp_structure_vp_pattern.adoc b/content/learn/vp_structure_vp_pattern.adoc index a90c4676d9..92fcd7272b 100644 --- a/content/learn/vp_structure_vp_pattern.adoc +++ b/content/learn/vp_structure_vp_pattern.adoc @@ -16,17 +16,17 @@ include::modules/comm-attributes.adoc[] The high level steps to create a validated pattern are as follows: -1. Identify the business case you want to address. -2. Use the Multicloud GitOps as a starting point by using the template to create a new Git repository in your local GitHub account. -3. Identify the technology components that you need. +1. Identify the business case you want to address. +2. Use link:/learn/creating-patterns-with-patternizer/[patternizer] to bootstrap a new pattern repository with all required scaffolding, or fork an existing pattern such as link:/patterns/multicloud-gitops[Multicloud GitOps] to start from a working example. +3. Identify the technology components that you need. 4. Ensure that the configuration of those components, and the integration points are handled in the pattern. == Best Practices for creating Validated Patterns Following these best practices, to create robust, scalable, and maintainable validated patterns that are easy to deploy and manage across various environments. -1. **Start with OpenShift Multicloud GitOps** - - When creating a validated pattern, begin with OpenShift Multicloud GitOps as your foundation. This is the most fundamental pattern and should serve as your base. +1. **Bootstrap your pattern with patternizer** + - When creating a new validated pattern, use link:/learn/creating-patterns-with-patternizer/[patternizer] to generate the required scaffolding. This is the fastest way to get started. Alternatively, you can fork the link:/patterns/multicloud-gitops[Multicloud GitOps] pattern as your foundation if you prefer to work from a fully working example. 2. **Centralize all manifests in a Git Repository** - Ensure that all pattern manifests, configuration files, and desired state definitions are stored in a Git repository. This provides a single source of truth and facilitates the use of GitOps for deployment.