validatedpatterns / docs Goto Github PK

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ has step

4. Verify that all applications are synchronized. Under the project multicloud-gitops-hub click the URL for the hub gitops server. The Vault application is not synched.

For a problem of figuring out where the user should find this see #342.

But assuming they should loot at the waffle menu / Hub ArgoCD, the sentence "The Vault application is not synched." is not what I see on a fresh ROSA cluster with steps followed as of yesterday. The vault application is reported as Healthy and Synced.

If it is expected that the vault gets synced after a while, the documentation should say so.

Also, on my fresh installation I see five applications, compared to the three in the screenshot on the page:

The page should clearly state what applications are expected and what they mean, what they represent or demonstrate.

I installed the setup to a new cluster called ocpmgt. It nicely has now ACM, ArgoCD and such. It is local-cluster for hub.

Then I created a new cluster and joined into ACM. I added manually label clusterGroup=region-one from ACM GUI. This had to be done due an error in instructions. If I am logged into management cluster as cluster admin, the instruction in managed-cluster.md fails:

▶ oc get region-one.cluster.open-cluster-management.io
error: the server doesn't have a resource type "region-one"

Reading https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/, there are steps like

vi values-global.yaml

git add values-global.yaml

git commit values-global.yaml

there. Content of that file is in turn

---
global:
  pattern: multicloud-gitops

  options:
    useCSV: false
    syncPolicy: Automatic
    installPlanApproval: Automatic

main:
  clusterGroupName: hub

  multiSourceConfig:
    enabled: true

However, it is not clear what CSV that useCSV is about, what syncing and installation that syncPolicy and installPlanApproval, or what the clusterGroupName value is for and what happens if any of those values get changed.

If there is something that the user following the https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ guidance should look for and change, it should be clearly documented.

If the file should be left as it is because for this pattern no changes are needed, that vi values-global.yaml step likely should not be there at all.

I have a question I don't see an answer to anywhere in the docs. Happy to put an answer here into a PR!

Question: Let's say I've forked a pattern repo (multicluster-gitops for example) and deployed a hub cluster with a few managed clusters. A few months go by and the upstream project has had several changes. Am I expected to pull and merge those changes into my fork and redeploy?

The pattern pages like https://validatedpatterns.io/patterns/industrial-edge/ seem to contain

<aside class="pf-c-jump-links pf-m-vertical sticky pf-m-expandable pf-m-non-expandable-on-2xl" aria-label="Table of contents"> ...

on the right which is empty and wastes space.

Moreover, when one tries to increase the size of the text with Ctrl-+, that white space grows and wastes even more space.

It should be turned to float or removed completely.

For example the devsecops pattern has a section on

• Credentials Required in Pattern

This provided minimal guidance on the scopes we should provide when setting up the GitHub token required for the secrets.

There's a typo in this diagram: https://github.com/hybrid-cloud-patterns/docs/blob/gh-pages/images/multicloud-gitops/logical-diagram.png

Prometheus doesn't scrap data. Well, that's a fun joke - but not the point of the diagram. :)

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ says

3. Verify that the Operators have been installed.
   a. To verify, in the OpenShift Container Platform web console, navigate to Operators → Installed Operators page.
   b. Check that the Operator is installed in the openshift-operators namespace and its status is Succeeded.

So the start of that step 3 talks about Operators (plural) but the step 3.b. only talks about Operator (singular).

Checking on my cluster, I see that in the openshift-operators namespace, two operators were installed:

• Red Hat OpenShift GitOps / Succeeded / Up to date / Plugin available
• Validated Patterns Operator / Succeeded / Up to date

The documentation should clarify if it is expected that these two operators should be seen there as a result of the previous steps.

In fact, two more operators seem to have been installed in the cluster:

• Advanced Cluster Management for Kubernetes / in namespace open-cluster-management / Succeeded / Up to date
• multicluster engine for Kubernetes / in namespace multicluster-engine / Succeeded / Up to date

If these are expected as well, the documentation should clearly spell that out too.

On https://validatedpatterns.io/patterns/multicloud-gitops/mcg-managed-cluster/#designate-cluster-as-a-managed-cluster-site the section Designate the new cluster as a managed cluster site says

To tag the cluster as clusterGroup=<managed-cluster-group>, complete the following steps.
[...]
2. oc label managedcluster.cluster.open-cluster-management.io/YOURCLUSTER site=managed-cluster

I believe the command

oc label managedcluster.cluster.open-cluster-management.io/YOURCLUSTER site=managed-cluster

does not affect the clusterGroup label in any way.

Should there be s/site=managed-cluster/clusterGroup=<managed-cluster-group>/ done to the page, or is there some deeper magic there, linking the site and clusterGroup labels?

I filed a couple of PRs (#312, #313) and both of them had the "Spellcheck Action / Spellcheck (pull_request)" check fail with

!!!Spelling check failed!!!
Error: Files in repository contain spelling errors

-- see https://github.com/validatedpatterns/docs/actions/runs/6282758510/job/17062556239?pr=312, https://github.com/validatedpatterns/docs/actions/runs/6282771115/job/17062583864?pr=313

And all I can think of is: So what? I did not put those files there, why do you bother me with this failure in my PR?

It'd be good to have that check either taught about the existing / desired content so that it does not report as spelling error something that is not, run it only on filed that actually got touched by the PR in question, run it only on the new content added by the PR in question, ... or disabled altogether.

The page https://validatedpatterns.io/learn/vault/ says

In order to setup HashiCorp Vault there are two different ways, both of which happen automatically as part of the make install command:

1. Inside the cluster directly when the helm value clusterGroup.insecureUnsealVaultInsideCluster is set to true. With this method a cronjob will run every five minutes inside the imperative namespace and unseal, initialize and configure the vault. The vault’s unseal keys and root token will be stored inside a secret called vaultkeys in the imperative namespace. It is considered best practice to copy the content of that secret offline, store it securely and then delete it.
2. On the user’s computer when the helm value clusterGroup.insecureUnsealVaultInsideCluster is set to false. This will store the json containing containing both vault root token and unseal keys inside a file called common/pattern-vault.init. It is recommended to encrypt this file or store it securely.

However, https://github.com/validatedpatterns/multicloud-gitops/blob/main/common/Changes.md#december-9-2022 says

Dropped insecureUnsealVaultInsideCluster (and file_unseal) entirely. Now vault is always unsealed via a cronjob in the cluster. It is recommended to store the imperative/vaultkeys secret offline securely and then delete it.

Should the documentation drop the second item on that page completely to align with the code?

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ has step

3. Verify that the Operators have been installed.
   a. To verify, in the OpenShift Container Platform web console, navigate to Operators → Installed Operators page.

followed by the

4. Verify that all applications are synchronized. Under the project multicloud-gitops-hub click the URL for the hub gitops server. The Vault application is not synched.

The step 3 clearly needs to be done as user admin (with cluster-admin role), in local-cluster menu, Administrator menu, because only there there is that Operators menu item.

However, after the admin user is done checking the Operators, it is not at all clear where they should follow with that step 4. There is no "URL under the project multicloud-gitops-hub".

There is a hub AppProject in the Red Hat OpenShift GitOps operator details page and in the Developer menu view under Topology there are multiple Deployments including hub-gitops-server -- is that one that the user should look at?

Or should the user use the waffle icon and either the Cluster Argo CD or Hub ArgoCD and re-login to those views? Which one?

Pages like https://validatedpatterns.io/patterns/industrial-edge/ or https://validatedpatterns.io/patterns/multicloud-gitops/ have in the Links line of the top frame link Help & Feedback with URL https://groups.google.com/g/hybrid-cloud-patterns.

Clicking that link produces

Content unavailable
Click here to try again.
If you've seen this page more than once, try switching accounts.

I've tried it with various accounts.

Each getting started document (eg. https://hybrid-cloud-patterns.io/patterns/retail/getting-started/ ) has a non-rendered {% include prerequisite-tools.md %}.

This file seems to not exist.

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-managed-cluster/#_verification says

Go to your managed cluster (edge) OpenShift console and check for the open-cluster-management-agent pod being launched. It might take a while for the RHACM agent and agent-addons to launch. After that, the OpenShift GitOps Operator is installed.

When following the steps on freshly provisioned OCP cluster, there is no open-cluster-management-agent pod there. There is a open-cluster-management-agent namespace there, with pods

$ oc get pods -n open-cluster-management-agent
NAME                                            READY   STATUS    RESTARTS      AGE
klusterlet-6f677f4ff-ddqqn                      1/1     Running   0             36m
klusterlet-registration-agent-75cdbdfbf-gn76d   1/1     Running   1 (35m ago)   36m
klusterlet-work-agent-75878ccd6d-s9zpr          1/1     Running   0             35m

Is that what the admin should be looking for?

There is also no agent-addons pod or namespace. However, there is a open-cluster-management-agent-addon namespace with

$ oc get pods -n open-cluster-management-agent-addon
NAME                                           READY   STATUS    RESTARTS   AGE
application-manager-647b4f5bb4-bfhzv           1/1     Running   0          37m
cert-policy-controller-86d5476b4b-gnrmh        1/1     Running   0          37m
cluster-proxy-proxy-agent-6d9b45bfcb-ww4k6     2/2     Running   0          37m
cluster-proxy-service-proxy-5577d574f4-68nls   1/1     Running   0          37m
config-policy-controller-6687b7f557-96qsh      2/2     Running   0          11m
governance-policy-framework-5859885c9d-fxj7n   2/2     Running   0          115s
iam-policy-controller-797bc896d8-qldvv         1/1     Running   0          37m
klusterlet-addon-search-c5c66cd77-662rd        1/1     Running   0          37m
klusterlet-addon-workmgr-5ddc9f654-h5zhz       1/1     Running   0          37m

Is that what the admin should expect?

In a discussion earlier there was confusion over the purpose of this section. It sounded like it would be read by users that are consuming the patterns. And therefore the complexity of the concepts discussed seems too deep for that sort of reader. And that would be right.

Maybe a change from Building and Build to Creating and Create would make it clearer that this section is for developers that want to use the framework to create their own pattern that might be contributed to hybrid-cloud-patterns.

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ says

To deploy the cluster by using the pattern.sh file, complete the following steps:

Login to your cluster by running the following command:

oc login

Yet when I do that with a regular user and then run ./pattern.sh make install, I get

$ ./pattern.sh make install
make -f common/Makefile operator-deploy
make[1]: Entering directory '/home/test/validatedpatterns/multicloud-gitops'
Checking prerequisites:
  Check for 'git helm oc ansible': OK
  Check for python-kubernetes: OK
  Check for kubernetes.core collection: OK
Checking repository:
  https://github.com/validatedpatterns/multicloud-gitops - branch main: Running inside a container: Skipping git ssh checks
Checking cluster:
  cluster-info: Error from server (Forbidden): services is forbidden: User "user" cannot list resource "services" in API group "" in the namespace "kube-system"
Error
make[1]: *** [common/Makefile:97: validate-cluster] Error 1
make[1]: Leaving directory '/home/test/validatedpatterns/multicloud-gitops'
make: *** [Makefile:12: operator-deploy] Error 2

Clearly the user used to log in the OCP cluster has to have some extra roles / privileges, potentially cloud-admin, but the documentation does not state which they are.

For security reasons all accounts used should be assumed to have minimal roles / privileges. So if some extra are needed for some of the steps in Validated Patterns, they should be clearly stated.

Hi,

I installed the hcp at spring, and now thought I update my fork with the community upstream. After merge I did make vault-unseal and I end up with an error. It seems the instructions on this page might be outdated, the unseal key file has changed format.

TASK [vault_utils : Parse "/home/itengval/src/multicloud-gitops/common/pattern-vault.init"] ******************************************************
fatal: [localhost]: FAILED! => {"msg": "the field 'args' has an invalid value ({'vault_init_json': \"{{ lookup('file', output_file_abs) | from_json }}\"}), and could not be converted to an dict.The error was: Expecting value: line 1 column 1 (char 0)\n\nThe error appears to be in '/home/itengval/src/multicloud-gitops/common/ansible/roles/vault_utils/tasks/vault_unseal.yaml': line 37, column 3, but may\nbe elsewhere in the file depending on the exact syntax problem.\n\nThe offending line appears to be:\n\n# and if file_unseal is true\n- name: Parse \"{{ output_file_abs }}\"\n  ^ here\nWe could be wrong, but this one looks like it might be an issue with\nmissing quotes. Always quote template expression brackets when they\nstart a value. For instance:\n\n    with_items:\n      - {{ foo }}\n\nShould be written as:\n\n    with_items:\n      - \"{{ foo }}\"\n"}

perhaps the instructions should be updated, as the file format seems to have changed to some json thing.

Hi,

While I was reading the docs I noticed there is error in docs layout. Some helm variables are not visible, the brackets need to be escaped in the source.

At leat this doc is having the problem:

https://github.com/hybrid-cloud-patterns/docs/blob/gh-pages/building-vps/structure.md

The {{ needs to be escaped.

On page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-managed-cluster/, the second sentence is

In the value-hub.yaml file, add a managedClusterCgroup for each cluster or group of clusters that you want to manage as one.

That "the" value-hub.yaml suggests that that file value-hub.yaml exists somewhere. But it does not seem to be present in the https://github.com/validatedpatterns/multicloud-gitops repo.

Should that be "Create a file named for example value-hub.yaml with content ..." or does that file exist somewhere under different name?

In https://validatedpatterns.io/patterns/multicloud-gitops/ and https://validatedpatterns.io/patterns/multicloud-gitops-portworx/, there is a sentence that starts with

Submitted code checks the continuous integration (CI) process, [...]

Typically, the code is checked by a CI, not the other way round. Since the rest of the page does not go into any details about how a code checks the CI, is it possible that the subject and the object are reversed in this sentence?

The page https://validatedpatterns.io/patterns/industrial-edge/ has a Note

Industrial Edge on OpenShift Container Platform 4.12 fails CI due to a Seldon issue. This only affects the Anomaly Detection AI/ML portion of the pattern. The rest of the pattern functions as designed. For more information on the Seldon issue, see SeldonIO/seldon-core#4339.

However, that SeldonIO/seldon-core#4339 has been marked resolved since 2023-03-08. Is the Note still valid?

Page https://validatedpatterns.io/patterns/industrial-edge/getting-started/ says in step 7 of How to deploy section

You can deploy the pattern using the Validated Patterns Operator directly. If you deploy the pattern using the Validated Patterns Operator, installed through Operator Hub, you will need to run make load-secrets through a terminal session on your laptop or bastion host.

However, running that yields

$ make load-secrets
make -f common/Makefile load-secrets
make[1]: Entering directory '/home/test/project/validatedpatterns/industrial-edge'
common/scripts/vault-utils.sh push_secrets industrial-edge
common/scripts/vault-utils.sh: line 31: ansible-playbook: command not found
make[1]: *** [common/Makefile:63: load-secrets] Error 127
make[1]: Leaving directory '/home/test/project/validatedpatterns/industrial-edge'
make: *** [Makefile:23: load-secrets] Error 2

Installation of Ansible is not listed in https://validatedpatterns.io/learn/quickstart/ linked from the second Prerequisites section.

Does that dependency need to be documented? Or should that command instead be ./pattern.sh make load-secrets?

https://hybrid-cloud-patterns.io/patterns/multicloud-gitops/ is a bit confusing and somewhat non accurate. Review it and improve it after the adoc changes land

Also workflow doc would need section on uninstall process. Before automation it could be manual steps.

Hi,

something has changed, and now if I run the makefile, it fails with the following if dnf install python3-kubernetes is not installed:

TASK [Check for vault namespace] ****************************************************************************************************************************************************************
An exception occurred during task execution. To see the full traceback, use -vvv. The error was: ModuleNotFoundError: No module named 'kubernetes'
fatal: [localhost]: FAILED! => {"changed": false, "error": "No module named 'kubernetes'", "failed_when_result": "The conditional check 'vault_ns_rc.resources | length == 0' failed. The error was: error while evaluating conditional (vault_ns_rc.resources | length == 0): 'dict object' has no attribute 'resources'", "msg": "Failed to import the required Python library (kubernetes) on iklap's Python /usr/bin/python3. Please read the module documentation and install it in the appropriate location. If the required library is installed, but Ansible is using the wrong Python interpreter, please consult the documentation on ansible_python_interpreter"}

So please add it as a prerequisite.

htmltest started at 02:49:00 on public/
========================================================================
contribute/contribute-to-docs/index.html
  target does not exist --- contribute/contribute-to-docs/index.html --> tools_and_setup.adoc
  target does not exist --- contribute/contribute-to-docs/index.html --> doc_guidelines.adoc
  target does not exist --- contribute/contribute-to-docs/index.html --> doc_guidelines.html#assembly-file-metadata
  target does not exist --- contribute/contribute-to-docs/index.html --> doc_guidelines.html#module-file-metadata

Seems the "link:.adoc" is not being rendered correctly here https://github.com/hybrid-cloud-patterns/docs/blame/main/modules/contributing.adoc#L43

Page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-managed-cluster/ shows three steps (1., 2., 3.) in the Deploying a managed cluster by using Red Hat Advanced Cluster Management section, and then it has a sentence

Now that RHACM is no longer deploying the managed cluster applications everywhere, you must indicate that the new cluster has the managed cluster role.

It is not clear if the steps that we just did caused that "RHACM is no longer deploying the managed cluster applications everywhere" or if that's something that changed in latest versions of ACM.

But more importantly, it is not clear, how the admin should "indicate that the new cluster has the managed cluster role".

The README continues to mention installing hugo and running hugo serve. The new way is to use the make serve, runs hugo in a container so there is no need to install hugo.

The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-cluster-sizing/ says

refer to the {ocp} documentation

That {ocp} looks like some failed template.

After finishing the steps at https://validatedpatterns.io/patterns/multicloud-gitops/ and https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ and https://validatedpatterns.io/patterns/multicloud-gitops/mcg-managed-cluster/, I see the Red Hat OpenShift GitOps operator installed on the managed cluster.

However, no applications (vault, config-demo, or hello-world) seem present on the managed cluster.

On the hub cluster, the managed cluster has "1 Policy violations" on its overview page, and displaying that violation I see

• acm-hub-ca-config-policy: violation - secrets [hub-ca] in namespace imperative is missing, and cannot be created, reason: namespaces "imperative" not found

The page https://validatedpatterns.io/learn/vault/ says:

1. Inside the cluster directly when the helm value clusterGroup.insecureUnsealVaultInsideCluster is set to true. With this method a cronjob will run every five minutes inside the imperative namespace and unseal, initialize and configure the vault. The vault’s unseal keys and root token will be stored inside a secret called vaultkeys in the imperative namespace. It is considered best practice to copy the content of that secret offline, store it securely and then delete it.
   [...]
   An example output is the following:
   [...]

However, it is not clear output of what is meant here.

Is it

oc get -o jsonpath='{.data.vault_data_json}' -n imperative secret/vaultkeys | base64 -d -

which should be run, or something else?

Also, that

It is considered best practice to copy the content of that secret offline, store it securely and then delete it.

part -- does that mean that the recommendation is to do

oc get -o yaml -n imperative secret/vaultkeys > secret-directory/vaultkeys.yaml
# backup secret-directory somehow
oc delete -n imperative secret/vaultkeys

? Or should that exported file secret-directory/vaultkeys.yaml be deleted?

Page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-cluster-sizing/ links to 3.11 documentation in the

System and environment requirements.

link. Based on https://access.redhat.com/support/policy/updates/openshift_noncurrent the 3.11 has been out of full support since June 2022.

A more contemporary OCP documentation should likely be linked.

The documentation requests that the production environment be tagged
clusterGroup=secured

But the values-hub.yaml from https://github.com/hybrid-cloud-patterns/multicluster-devsecops assumes the label
clusterGroup=prod

If we don't apply the correct label then services aren't deployed to production