Please do not ask core maintainers to cherry pick your patch though we will be happy to review it and help merge it once the -cherry pick PR has been submitted.
+cherry pick PR has been submitted using one of the methods below. +Add a comment like the following to the PR you wish to cherry pick. +
/cherrypick 18.0.0-proposed
+If there is a merge conflict, +then method 1 will not work and you will need to use method 2.
+If you can send a PR to this repository then you can create a cherry
pick using the git command line tools without requiring any
additional privileges. For example, the following produces a
@@ -710,7 +797,7 @@
The Architectures repository may be used with to create validated architectures (VAs), represented as custom resources (CRs) for openstack-k8s-operators. It may also be used to create deployed topologies (DTs) which should only be used for testing.
"},{"location":"dt/","title":"Deployed Topologies","text":"All validated architectures (VAs) are deployed topologies (DTs), but not all DTs are VAs.
DTs represent CI optimizations. We design them to test lots of things together so we can have as few of them as possible. Before proposing a new DT to test something, consider if an update to an existing DT will achieve the same result.
"},{"location":"contributing/cherry-picking/","title":"Getting your PR into a stable branch","text":"After your PR merges into the main branch you should open a PR to cherry pick it into a stable branch if appropriate. For example, you may want your patch to be in the 18.0.0-proposed branch.
If you anticipate that your PR should be cherry picked then please tag it accordingly. For example we have a needs-18.0.0-proposed-cherry-pick tag. If we think a patch should be in a stable branch, then we will apply that tag to your PR to remind you to follow up to send in a cherry pick.
Please do not ask core maintainers to cherry pick your patch though we will be happy to review it and help merge it once the cherry pick PR has been submitted.
If you can send a PR to this repository then you can create a cherry pick using the git command line tools without requiring any additional privileges. For example, the following produces a cherry-pick within a personal fork of the architecture repository.
git remote add upstream git@github.com:openstack-k8s-operators/architecture.git \ngit fetch upstream\ngit checkout -b 18.0.0-proposed upstream/18.0.0-proposed\ngit push origin 18.0.0-proposed\ngit log origin/main\ngit cherry-pick <commit hash>\ngit push origin 18.0.0-proposed\n(cherry picked from <commit hash>) to the bottom of your commit message."},{"location":"contributing/documentation/","title":"Contributing to documentation","text":""},{"location":"contributing/documentation/#rendering-documentation-locally","title":"Rendering documentation locally","text":"Install docs build requirements into virtualenv:
python3 -m venv local/docs-venv\nsource local/docs-venv/bin/activate\npip install -r docs/doc_requirements.txt\nServe docs site on localhost:
mkdocs serve\nClick the link it outputs. As you save changes to files modified in your editor, the browser will automatically show the new content.
"},{"location":"contributing/documentation/#structure-and-content","title":"Structure and Content","text":"The MkDocs output generates nice looking HTML pages that link to the content genereated by github.com.
This is because the authors believe it's more valuable to have github.com/openstack-k8s-operators/architecture be navigable relative to the github pages which contain the CRs, than have all of the documentation isolated in the docs directory. Thus, there are non-relative links in the MkDocs content to the pages hosted on github.
Though it's possible to create symbolic links to README files or link to a directory above the docs directory, the resulting HTML will contain invalid links unless all READMEs are moved out of the directories that they describe. However, this would make reading the CRs more complicated as they wouldn't have a corresponding README.
Thus, if you add a new VA or DT, then please just link it in the mkdocs.yml file, similar to the way the HCI VA is linked, in to keep the MkDocs output up to date.
Contributions to the architecture repository are always welcomed and encouraged. In order to avoid causing regressions to the repository and to prove that the contributions are working as intended, all pull requests are expected to provide proof of validation.
The simplest way is to use the reproducer functionality in the CI-Framework.
"},{"location":"contributing/pull-request-testing/#using-the-reproducer-role","title":"Using the reproducer role","text":"Additional parameters can be passed to the reproducer role of the CI-Framework, allowing you validate changes to the architecture repository remain functional within the contexts of kustomize and CI-Framework itself (which consumes the contents of the architecture repository).
Use the reproducer.yml playbook within the CI-Framework to deploy the HCI validated architecture aka VA1 (or any other validated architecture or deployment topology that might be affected) with an environment file containing parameters denoting which branch and repository to deploy with. The custom parameter filename is not important, as long as it is passed to Ansible, and is valid.
ansible-playbook reproducer.yml \\\n -i custom/inventory.yml \\\n -e cifmw_target_host=hypervisor-1 \\\n -e @scenarios/reproducers/va-hci.yml \\\n -e @scenarios/reproducers/networking-definition.yml \\\n -e @custom/default-vars.yaml \\\n -e @custom/secrets.yml \\\n -e @custom/test-my_pr_branch.yml\nThe test-my_pr_branch.yml file contains parameters that identifies the remote git repository and branch name to deploy.
test-my_pr_branch.yml
remote_base_dir: \"/home/zuul/src/github.com/openstack-k8s-operators\"\ncifmw_reproducer_repositories:\n- src: \"https://github.com/<FORKED_ORGANIZATION>/architecture\"\n dest: \"{{ remote_base_dir }}/architecture\"\n version: <BRANCH_TO_DEPLOY>\nOnce your environment has been deployed, provide any relevant output showing that the deployment was successful, and that the environment continues to operate nominally. Provide any additional output showing that the changes to the architecture repository have been deployed and are functioning as intended by the pull request. You can SSH into the controller-0 machine and review the contents of /home/zuul/src/github.com/openstack-k8s-operators/architecture which contains the content as configured by the test-<NAME>.yml parameter file.
The kustomize command builds and results in the OpenStack control plane definitions and its dependent Custom Resources (CR).
kustomize build architecture/examples/va/hci > control-plane.yaml\ncontrol-plane.yaml file contains CRs for the NodeNetworkConfigurationPolicy (NNCP), the NetworkAttachmentDefinition, MetalLB resources and OpenStack resources. Is it possible to create a CR file with less custom resources?"},{"location":"faq/cr_by_components/#answer","title":"Answer","text":"Yes, it's possible to create CR files with less components and wait before applying each CR file. E.g. the file nncp.yaml would contain only NodeNetworkConfigurationPolicy CRs and NetworkAttachmentDefinition and other CRs could exist in another file like networking.yaml. The following process may be used to generate these files using kustomize.
components:\n- ../../lib/nncp\nkustomize build architecture/examples/va/hci > nncp.yaml\ncomponents:\n- ../../lib/networking\nkustomize build architecture/examples/va/hci > networking.yaml\nThe above process may be continued for each component.
Note that va/hci/kustomization.yaml is not the same file as examples/va/hci/kustomization.yaml. /example/va/hci is a specific example of a given VA where as /va/hci is a generic HCI VA that may be customised and shared in multiple examples or composed to make a larger VA.
This process will work for VAs (and DTs) besides HCI, but the paths may be different. E.g. examples/va/nfv/sriov/kustomization.yaml differs from va/nfv/sriov/kustomization.yaml and the later is in an nfv subdirectory so each component is referred to using - ../../../lib/ instead of - ../../lib/.
The Architectures repository may be used with to create validated architectures (VAs), represented as custom resources (CRs) for openstack-k8s-operators. It may also be used to create deployed topologies (DTs) which should only be used for testing.
"},{"location":"dt/","title":"Deployed Topologies","text":"All validated architectures (VAs) are deployed topologies (DTs), but not all DTs are VAs.
DTs represent CI optimizations. We design them to test lots of things together so we can have as few of them as possible. Before proposing a new DT to test something, consider if an update to an existing DT will achieve the same result.
"},{"location":"contributing/cherry-picking/","title":"Getting your PR into a stable branch","text":"After your PR merges into the main branch you should open a PR to cherry pick it into a stable branch if appropriate. For example, you may want your patch to be in the 18.0.0-proposed branch.
If you anticipate that your PR should be cherry picked then please tag it accordingly. For example we have a needs-18.0.0-proposed-cherry-pick tag. If we think a patch should be in a stable branch, then we will apply that tag to your PR to remind you to follow up to send in a cherry pick.
Please do not ask core maintainers to cherry pick your patch though we will be happy to review it and help merge it once the cherry pick PR has been submitted using one of the methods below.
"},{"location":"contributing/cherry-picking/#method-1","title":"Method 1","text":"Add a comment like the following to the PR you wish to cherry pick.
/cherrypick 18.0.0-proposed\nIf there is a merge conflict, then method 1 will not work and you will need to use method 2.
"},{"location":"contributing/cherry-picking/#method-2","title":"Method 2","text":"If you can send a PR to this repository then you can create a cherry pick using the git command line tools without requiring any additional privileges. For example, the following produces a cherry-pick within a personal fork of the architecture repository.
git remote add upstream git@github.com:openstack-k8s-operators/architecture.git \ngit fetch upstream\ngit checkout -b 18.0.0-proposed upstream/18.0.0-proposed\ngit push origin 18.0.0-proposed\ngit log origin/main\ngit cherry-pick <commit hash>\ngit push origin 18.0.0-proposed\n(cherry picked from <commit hash>) to the bottom of your commit message."},{"location":"contributing/documentation/","title":"Contributing to documentation","text":""},{"location":"contributing/documentation/#rendering-documentation-locally","title":"Rendering documentation locally","text":"Install docs build requirements into virtualenv:
python3 -m venv local/docs-venv\nsource local/docs-venv/bin/activate\npip install -r docs/doc_requirements.txt\nServe docs site on localhost:
mkdocs serve\nClick the link it outputs. As you save changes to files modified in your editor, the browser will automatically show the new content.
"},{"location":"contributing/documentation/#structure-and-content","title":"Structure and Content","text":"The MkDocs output generates nice looking HTML pages that link to the content genereated by github.com.
This is because the authors believe it's more valuable to have github.com/openstack-k8s-operators/architecture be navigable relative to the github pages which contain the CRs, than have all of the documentation isolated in the docs directory. Thus, there are non-relative links in the MkDocs content to the pages hosted on github.
Though it's possible to create symbolic links to README files or link to a directory above the docs directory, the resulting HTML will contain invalid links unless all READMEs are moved out of the directories that they describe. However, this would make reading the CRs more complicated as they wouldn't have a corresponding README.
Thus, if you add a new VA or DT, then please just link it in the mkdocs.yml file, similar to the way the HCI VA is linked, in to keep the MkDocs output up to date.
Contributions to the architecture repository are always welcomed and encouraged. In order to avoid causing regressions to the repository and to prove that the contributions are working as intended, all pull requests are expected to provide proof of validation.
The simplest way is to use the reproducer functionality in the CI-Framework.
"},{"location":"contributing/pull-request-testing/#using-the-reproducer-role","title":"Using the reproducer role","text":"Additional parameters can be passed to the reproducer role of the CI-Framework, allowing you validate changes to the architecture repository remain functional within the contexts of kustomize and CI-Framework itself (which consumes the contents of the architecture repository).
Use the reproducer.yml playbook within the CI-Framework to deploy the HCI validated architecture aka VA1 (or any other validated architecture or deployment topology that might be affected) with an environment file containing parameters denoting which branch and repository to deploy with. The custom parameter filename is not important, as long as it is passed to Ansible, and is valid.
ansible-playbook reproducer.yml \\\n -i custom/inventory.yml \\\n -e cifmw_target_host=hypervisor-1 \\\n -e @scenarios/reproducers/va-hci.yml \\\n -e @scenarios/reproducers/networking-definition.yml \\\n -e @custom/default-vars.yaml \\\n -e @custom/secrets.yml \\\n -e @custom/test-my_pr_branch.yml\nThe test-my_pr_branch.yml file contains parameters that identifies the remote git repository and branch name to deploy.
test-my_pr_branch.yml
remote_base_dir: \"/home/zuul/src/github.com/openstack-k8s-operators\"\ncifmw_reproducer_repositories:\n- src: \"https://github.com/<FORKED_ORGANIZATION>/architecture\"\n dest: \"{{ remote_base_dir }}/architecture\"\n version: <BRANCH_TO_DEPLOY>\nOnce your environment has been deployed, provide any relevant output showing that the deployment was successful, and that the environment continues to operate nominally. Provide any additional output showing that the changes to the architecture repository have been deployed and are functioning as intended by the pull request. You can SSH into the controller-0 machine and review the contents of /home/zuul/src/github.com/openstack-k8s-operators/architecture which contains the content as configured by the test-<NAME>.yml parameter file.
The kustomize command builds and results in the OpenStack control plane definitions and its dependent Custom Resources (CR).
kustomize build architecture/examples/va/hci > control-plane.yaml\ncontrol-plane.yaml file contains CRs for the NodeNetworkConfigurationPolicy (NNCP), the NetworkAttachmentDefinition, MetalLB resources and OpenStack resources. Is it possible to create a CR file with less custom resources?"},{"location":"faq/cr_by_components/#answer","title":"Answer","text":"Yes, it's possible to create CR files with less components and wait before applying each CR file. E.g. the file nncp.yaml would contain only NodeNetworkConfigurationPolicy CRs and NetworkAttachmentDefinition and other CRs could exist in another file like networking.yaml. The following process may be used to generate these files using kustomize.
components:\n- ../../lib/nncp\nkustomize build architecture/examples/va/hci > nncp.yaml\ncomponents:\n- ../../lib/networking\nkustomize build architecture/examples/va/hci > networking.yaml\nThe above process may be continued for each component.
Note that va/hci/kustomization.yaml is not the same file as examples/va/hci/kustomization.yaml. /example/va/hci is a specific example of a given VA where as /va/hci is a generic HCI VA that may be customised and shared in multiple examples or composed to make a larger VA.
This process will work for VAs (and DTs) besides HCI, but the paths may be different. E.g. examples/va/nfv/sriov/kustomization.yaml differs from va/nfv/sriov/kustomization.yaml and the later is in an nfv subdirectory so each component is referred to using - ../../../lib/ instead of - ../../lib/.