validatedpatterns / docs Goto Github PK
View Code? Open in Web Editor NEWValidated Patterns documentation
Home Page: https://validatedpatterns.io/
License: Apache License 2.0
Validated Patterns documentation
Home Page: https://validatedpatterns.io/
License: Apache License 2.0
The page https://validatedpatterns.io/patterns/multicloud-gitops/mcg-getting-started/ has step
- Verify that all applications are synchronized. Under the project
multicloud-gitops-hub
click the URL for thehub
gitopsserver
. 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
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
- 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 theopenshift-operators
namespace and its status isSucceeded
.
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:
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:
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:
- 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.
- 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
- 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
- Verify that all applications are synchronized. Under the project
multicloud-gitops-hub
click the URL for thehub
gitopsserver
. 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 theopen-cluster-management-agent
pod being launched. It might take a while for the RHACM agent andagent-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 amanagedClusterCgroup
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 runmake 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
namespaces "imperative" not found
The page https://validatedpatterns.io/learn/vault/ says:
- 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
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
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.