From b9a1f1b8faee6b87166ca035240042cebb1ff8c1 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 29 Aug 2024 14:00:46 +0300 Subject: [PATCH 01/74] Add contributor guide for documentation (#164) Signed-off-by: Gergely Csatari --- .../docs/guides/contributor-guides/doc-faq.md | 14 --- .../contributor-guides/documentation.md | 88 +++++++++++++++++++ 2 files changed, 88 insertions(+), 14 deletions(-) delete mode 100644 content/en/docs/guides/contributor-guides/doc-faq.md create mode 100644 content/en/docs/guides/contributor-guides/documentation.md diff --git a/content/en/docs/guides/contributor-guides/doc-faq.md b/content/en/docs/guides/contributor-guides/doc-faq.md deleted file mode 100644 index b4dfb257..00000000 --- a/content/en/docs/guides/contributor-guides/doc-faq.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Nephio Documentation System FAQ -description: > - Frequently Asked Questions on the Nephio Documentation system -weight: 5 ---- - -1. How do I check the documentation links on the documentation before I check in my changes? - - Install and run *linkspector* - ``` - npm install -g @umbrelladocs/linkspector - linkinspector check -c .linkspector.yml - ``` \ No newline at end of file diff --git a/content/en/docs/guides/contributor-guides/documentation.md b/content/en/docs/guides/contributor-guides/documentation.md new file mode 100644 index 00000000..bf131a7b --- /dev/null +++ b/content/en/docs/guides/contributor-guides/documentation.md @@ -0,0 +1,88 @@ +--- +title: Documentation +description: > + Contributors guide for the Nephio documentation +weight: 5 +--- + +## Framework + +The Nephio documentation is built with the .md / Hugo / Docsy / Netlify framework. + +* **.md:** The documentation itself is written in Markdown (,md) with some Hugo and Docsy related extensions. The .md + files are stored and managed in a Git repo in [nephio-project/docs](https://github.com/nephio-project/docs). +* **Hugo:** [Hugo](https://gohugo.io/) is used to render the documentation fo static html pages. +* **Docsy:** [Docsy](https://www.docsy.dev/) is a theme for Hugo what we use to provide the basic structure and look + and feel of the documentation. +* **Netlify:** [Netlify](https://www.netlify.com/) is a service to host documentation. We are hosting the Nephio + documentation from here. + +## Creating issues + +Documentation issues are handled in the nephio-project/nephio repository's [issue handler](https://github.com/nephio-project/nephio/issues). +Add the *area/docs* and the *documentation* labels to the issues created for the documentation. + +## Style guide + +* Use US English in the documentation +* Do not add manually a table of contents to the documents. Hugo and Docsy takes care of this. +* Do not use H1 (#) headers in the documents. Docsy generates a H1 header to every document consistent with the title + of the document. Start the headings with H2 (##) +* Use the built in alerts for notes and alerts + + ```go-html-template + {{%/* alert title="Warning" color="primary" */%}} + This is a note. + {{%/* /alert */%}} + ``` + + ```go-html-template + {{%/* alert title="Warning" color="warning" */%}} + This is a warning. + {{%/* /alert */%}} + ``` +* Colors to be used when creating figures are [here](https://color.adobe.com/Nephio-secondary-colors-color-theme-0bbcdea2-0533-4ab3-812f-f752f30b5b40/) +* If you add any commands to the content inline surround the comand with backticks (\` \`), like \`ls -la\` +* Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics (\* \*) to mark any + inline IP address, domain name, file name, file location or similar. +* Whenever possible define the type of code for your code blocks + * \```bash for all shell blocks + * \```golang for all Go blocks + * \```yaml for all YAML blocks + * \``` yang for all YANG blocks + * a full list of language identifyers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages) +* Do not add any TBDs to the documentation. If something is missing create an [issue](https://github.com/nephio-project/nephio/issues) for it + +## How to contribute + +Follow the Nephio contribution process, based on GitHub pull requests and Prow. Contributions to the Nephio +documentation require the [Nephio CLA](https://contributor.easycla.lfx.linuxfoundation.org/#/cla/project/084c4c00-cece-4fe0-b259-7132f445025e/user/2e82f427-4b62-48c8-a43f-d46dc74cc74b). + +### Build your environment + +Following the description [here](https://github.com/nephio-project/docs?tab=readme-ov-file#setting-up-the-environment). + +### Tests before submitting a pull request + +* Build and deploy the documentation locally + * run `hugo serve` +* Build in a same way as Netlify is doing it + * run `hugo --gc --minify` +* Check links + * Install and run [linkspector](https://github.com/UmbrellaDocs/linkspector) + ```bash + npm install -g @umbrelladocs/linkspector + linkinspector check -c .linkspector.yml + ``` + +### Checks before submitting a pr + +## FAQ + +1. How do I check the documentation links on the documentation before I check in my changes? + + Install and run *linkspector* + ``` + npm install -g @umbrelladocs/linkspector + linkinspector check -c .linkspector.yml + ``` \ No newline at end of file From e21268894e025380ee24e8afdd6ec810a92eff8c Mon Sep 17 00:00:00 2001 From: Istvan Kispal Date: Thu, 29 Aug 2024 13:02:46 +0200 Subject: [PATCH 02/74] Complete TODO tasks in the environment setup doc (#166) The following TODO tasks explicitly mentioned in the text were completed, thus removed from the docs: - WSL2 with Docker Desktop setup was checked and working as expected - `sed` is no longer used as part of the mainstream dev process, and in the Google-specific parts, where it is still used, it doesn't require POSIX specific behavior --- .../porch/contribturos-guide/environment-setup.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/content/en/docs/porch/contribturos-guide/environment-setup.md b/content/en/docs/porch/contribturos-guide/environment-setup.md index aeb6eeed..0e944dd8 100644 --- a/content/en/docs/porch/contribturos-guide/environment-setup.md +++ b/content/en/docs/porch/contribturos-guide/environment-setup.md @@ -15,28 +15,22 @@ through the [Starting with Porch tutorial](../using-porch/install-and-using-porc As your Dev environment, you can run the code on a remote VM and use the [VSCode Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) plugin to connect to it. -TODO: re-check WSL2 + Docker Desktop setup {{% /alert %}} ## Extra steps for MacOS users The script the `make deployment-config` target to generate the deployment files for porch. The scripts called by this -make target use recent `bash` additions and expect the gnu version of the `sed` command. MacOS comes with `bash` 3.x.x -by default and with a version of `sed` that is incompatible with gnu `sed`. TODO: check if sed is indeed still used. +make target use recent `bash` additions. MacOS comes with `bash` 3.x.x 1. Install `bash` 4.x.x or better of `bash` using homebrew, see [this this post for details](https://apple.stackexchange.com/questions/193411/update-bash-to-version-4-0-on-osx) -2. Install `gsed` using homebrew, see - [this post for details](https://stackoverflow.com/questions/4247068/sed-command-with-i-option-failing-on-mac-but-works-on-linux) -3. `sudo ln -s /opt/homebrew/bin/gsed /opt/homebrew/bin/sed` create a soft link for `sed` from `gsed` -4. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin` +2. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin` {{% alert title="Note" color="primary" %}} -The changes above **permanently** change the `bash` version and `sed` for **all** applications and may cause side -effects. You may wish to revert the changes (particularly the `sed-->gsed` soft link) when you complete your work on -Porch. +The changes above **permanently** change the `bash` version for **all** applications and may cause side +effects. {{% /alert %}} From 6827a9b3641f3b7e02ff7f3c240af26319222d0c Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Thu, 29 Aug 2024 15:04:46 +0200 Subject: [PATCH 03/74] language corrections for r1 release notes. (#165) --- content/en/docs/release-notes/R1.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/content/en/docs/release-notes/R1.md b/content/en/docs/release-notes/R1.md index c3cbbc65..d98e9bbe 100644 --- a/content/en/docs/release-notes/R1.md +++ b/content/en/docs/release-notes/R1.md @@ -7,7 +7,7 @@ weight: 1 ## Prerequisites -Refer to the [Install Guide](/content/en/docs/guides/install-guides/_index.md) +See the [Install Guide](/content/en/docs/guides/install-guides/_index.md) for the prerequisites for the supported environments. ## Support matrix @@ -30,7 +30,7 @@ for the management cluster. ### API -CRDs are provided for UPF, SMF, and AMF 5G Core services. +CRDs are provided for the UPF, SMF, and AMF 5G Core services. ### Web UI @@ -43,7 +43,7 @@ The following packages are supported: * Kpt packages for all [free5GC](https://free5gc.org/) services. * Packages for the core Nephio services. -* Packages for the Cluster API services for cluster creation. +* Packages for the Cluster API services, for cluster creation. * Packages for the dependent services. ### Functionalities @@ -51,8 +51,8 @@ The following packages are supported: The following functionalities are supported: * Create Kubernetes clusters. This functionality is based on the Cluster API. - At this time, only Kubernetes in Docker (KIND) cluster creation is supported. -* Fully automated deployment of UPF, SMF, and AMF services of + Currently, only Kubernetes in Docker (KIND) cluster creation is supported. +* Fully automated deployment of the UPF, SMF, and AMF services of [free5GC](https://free5gc.org/). These are deployed on multiple clusters based on the user's intent, expressed via the CRDs. * Deployment of other free5GC functions. @@ -65,10 +65,10 @@ The following limitations need to be borne in mind: * For infrastructure automation, only the creation of KIND clusters is supported. -* Inter-cluster networking is not dynamic. Therefore, as more clusters are - deployed, some manual tweaking will be needed for inter-cluster communications. +* Intercluster networking is not dynamic. Therefore, as more clusters are + deployed, some manual tweaking will be needed for intercluster communications. * Provisioning of VLAN interfaces on nodes is currently performed manually. -* Feedback of workload deployments from workload clusters to the Management +* Feedback of workload deployments from workload clusters to the management cluster is limited. You may need to connect directly to the workload cluster via kubectl to debug any deployment issues. * Web UI features are limited to the viewing and editing of packages, as well as @@ -76,7 +76,7 @@ The following limitations need to be borne in mind: be added in subsequent releases. * When the capacities of the UPF, SMF, and AMF NFs are changed, the free5GC Operator on the workload cluster will instantiate a new POD with correspondingly - modified resources (CPU, memory, and so on) During this process, the POD will + modified resources (CPU, memory, and so on). During this process, the POD will restart. This is a limitation of free5GC. * Only Gitea works with automated cluster provisioning to create new repositories and join them to Nephio. To use a different Git provider, you @@ -93,8 +93,8 @@ The following limitations need to be borne in mind: * When deploying the sandbox environment on an Ubuntu VM running on OpenStack, the deployment may fail. Reinstalling the packages will get around this issue. * Packages may take time to be approved by the auto-approval controller. If they - appear to have frozen, it may help to restart Porch and the Nephio controllers - using the following commands: + appear to have frozen, it may help to restart the Porch and the Nephio + controllers using the following commands: ```bash kubectl -n porch-system rollout restart deploy porch-server From b5a8fd5ff4eddd44dbd66108b73aafaacda72a50 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Thu, 29 Aug 2024 15:07:49 +0200 Subject: [PATCH 04/74] language corrections for Nephio (#162) Signed-off-by: Michael Greaves --- README.md | 2 + content/en/docs/_index.md | 130 +++++++++++++++++++------------------- 2 files changed, 68 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 452846bc..f2727ab0 100644 --- a/README.md +++ b/README.md @@ -121,6 +121,7 @@ it is manageable via Nephio. Please use the documentation links below to learn more about Nephio, or check out our [Learning Nephio](https://wiki.nephio.org/display/HOME/Learning+with+Nephio+R1) series. The video series includes a [demo video](https://youtu.be/mFl71sy2Pdc) and short articles about different aspects of Nephio. ## User Documentation + * [Release Notes for each Nephio release](https://docs.nephio.org/docs/release-notes/) * [Demo Sandbox Environment Installation](https://docs.nephio.org/docs/guides/install-guides/) * [User Guide](https://docs.nephio.org/docs/guides/user-guides/) @@ -131,3 +132,4 @@ Please use the documentation links below to learn more about Nephio, or check ou * [Developer Guide](https://docs.nephio.org/docs/guides/contributor-guides/) * [Project Resources](https://github.com/nephio-project/docs/blob/main/resources.md) + diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index e8298515..5b7601e3 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -5,89 +5,91 @@ menu: {main: {weight: 20}} weight: 1 --- -Our mission is "to deliver carrier-grade, simple, open, Kubernetes-based cloud -native intent automation and common automation templates that materially -simplify the deployment and management of multi-vendor cloud infrastructure and -network functions across large scale edge deployments." But what does that mean? +Our mission is "to deliver carrier-grade, simple, open, Kubernetes-based +cloud-native intent automation and common automation templates that materially +simplify the deployment and management of multivendor cloud infrastructure and +network functions across large-scale edge deployments." But what does that mean? With this release and the accompanying documentation, we hope to make that clear. -The mission outlines the basic goals and the [About Nephio +Our mission outlines the basic goals. The [About Nephio page](https://nephio.org/about/) describes the high-level architecture of Nephio. It is important to understand that Nephio is about managing complex, -inter-related workloads *at scale*. If we simply want to deploy a network -function, existing methods like Helm charts and scripts are sufficient. -Similarly, if we want to deploy some infrastructure, then using existing -Infrastructure-as-Code tools can accomplish that. Configuring running network -functions can already be done today with element managers. +interrelated workloads *at scale*. If we simply want to deploy a network +function, then existing methods, such as Helm charts and scripts, are +sufficient. Similarly, if we want to deploy some infrastructure, then using +existing Infrastructure-as-Code tools can accomplish that. Configuring running +network functions can already be done today with element managers. -So, why do we need Nephio? The problems Nephio wants to solve start only -once we try to operate at scale. "Scale" here does not simply mean "large number -of sites". It can be across many different dimensions: number of sites, number -of services, number of workloads, size of the individual workloads, number of -machines needed to operate the workloads, complexity of the organization running -the workloads, and other factors. The fact that our infrastructure, workloads, -and workload configurations are all interconnected dramatically increases -the difficulty in managing these architectures at scale. +Why do we need Nephio? The problems Nephio aims to solve start only +once we try to operate at scale. "Scale", in this case, does not simply mean +"a large number of sites". "Scale" can encompass many different areas: the +number of sites, services, and workloads, the size of each individual workload, +the number of machines needed to operate the workloads, the complexity of the +organization running the workloads, and other factors. The fact that our +infrastructure, workloads, and workload configurations are all interconnected +greatly increases the difficulty in managing these architectures at scale. To address these challenges, Nephio follows a [few basic principles](https://cloud.google.com/blog/topics/telecommunications/network-automation-csps-linus-nephio-cloud-native) -that experience has shown to enable higher scaling with less management overhead: -- *Intent-driven* to enable the user to specify "what they want" and let the - system figure out "how to make that happen". -- *Distributed actuation* to increase reliability across widely distributed - fleets. -- *Uniformity in systems* to reduce redundant tooling and processes, and - simplify operations. +that experience has shown to enable higher scaling with fewer management +overheads. These principles are as follows: +- It is *Intent-driven* to enable the user to specify what they want and + let the system figure out how to make that happen. +- It has *Distributed actuation* to increase reliability across widely + distributed fleets. +- It has *Uniformity in systems* to reduce redundant tooling and processes, + and simplify operations. -Additionally, Nephio leverages the "configuration as data" principle. This +Nephio also leverages the "configuration as data" principle. This methodology means that the "intent" is captured in a machine-manageable format that we can treat as data, rather than code. In Nephio, we use the Kubernetes -Resource Model (KRM) to capture intent. As Kubernetes itself is already an +Resource Model (KRM) to capture the intent. As Kubernetes itself is already an intent-driven system, this model is well suited to our needs. -To understand why we need to treat configuration as data, let's consider an -example. In a given instance, a network function may have, say, 100 parameters -that need to be decided upon. When we have 100 such network functions, across -10,000 clusters, this results in 100,000,000 inputs we need to define and -manage. Handling that sheer number of values, with their interdependencies and a need -for consistency management between them, requires *data management* techniques, -not *code* management techniques. This is why existing methodologies begin to -break down at scale, particular edge-level scale. +To understand why we need to treat configuration as data, let us consider an +example. In a given instance, a network function may have, for example, 100 +parameters that need to be decided upon. 100 such network functions, across +10,000 clusters, results in 100,000,000 inputs that need to be defined and +managed. Handling such a large number of values, with their interdependencies +and a need for consistency management between them, requires *data management* +techniques, rather than *code* management techniques. This is why existing +methodologies begin to break down at scale, particular at the edge-level scale. -Consider as well that no single human will understand all of those values. Those -values relate not only to workloads, but also to the infrastructure we need to -support those workloads. They require different areas of expertise and different -organizational boundaries of control. For example, you will need input from -network planning (IP address, VLAN tags, ASNs, etc.), input from -compute infrastructure teams (types of hardware or VMs available, OS available), -Kubernetes platform teams, security teams, network function experts, and many, -many other individuals and teams. Each of those teams will have their own -systems for tracking the values they control, and processes for allocating and -distributing those values. This coordination between teams is a fundamental -*organizational* problem with operating at scale. The existing tools and methods -do not even attempt to address these parts of the problem; they *start* once all -of the "input" decisions are made. +It should also be considered that no individual human will be able to understand +all of these values. These values relate not only to the workloads, but also to +the infrastructure that is required to support the workloads. They require +different areas of expertise and different organizational boundaries of control. +For example, you will need input from network planning (IP address, VLAN tags, +ASNs, and so on), input from the compute infrastructure teams (types of hardware, +or available VMs or OSs), the Kubernetes platform teams, the security teams, the +network function experts, and many other individuals and teams. Each of these +teams will have their own systems for tracking the values they control, as well +as processes for allocating and distributing those values. This coordination +between teams is a fundamental *organizational* problem with operating at scale. +The existing tools and methods do not even attempt to address these parts of the +problem. They *start* once all of the "input" decisions are made. -The Nephio project believes the organizational challenge around figuring out -these values is actually one of the primary limiting factors to achieving -efficient management of large, complex systems at scale. This gets even harder -when we realize that we need to manage changes to these values over time, and -understand how changes to some values implies the need to change other values. -This challenge is currently left to ad hoc processes that differ across +The Nephio project believes that the organizational challenge of figuring out +these values is one of the primary limiting factors to achieving the efficient +management of large, complex systems at scale. This challenge becomes even +greater when we understand the need to manage the changes to these values over +time, and how changes to some values implies the need to change other values. +This challenge is currently left to ad-hoc processes that differ across organizations. Nephio is working on how to structure the intent to make it manageable using data management techniques. -This release of Nephio focuses: -- Demonstrating the core Nephio principles such as Configuration-as-Data and +This Nephio release focuses on the following: +- Demonstrating the core Nephio principles, such as Configuration-as-Data and leveraging the intent-driven, active-reconciliation nature of Kubernetes. - Infrastructure orchestration/automation using controllers based on - the Cluster API. At this time only KIND cluster creation is supported. -- Orchestration/automation of 5G Core and RAN network functions deployment and - management. + the Cluster API. Currently, only Kubernetes in Docker (KIND) cluster creation + is supported. +- Orchestration/automation of the deployment and management of 5G Core and RAN + networks. -While the current releases uses Cluster API, KIND, and free5gc/OAI for demonstration -purposes, the exact same principles and even code can be used for managing other -infrastructure and network functions. The *uniformity in systems* principle -means that as long as something is manageable via the Kubernetes Resource Model, -it is manageable via Nephio. +While the current release uses Cluster API, KIND, and free5gc/OAI for +demonstration purposes, the same principles and code can be used for managing +other infrastructure and network functions. The *uniformity in systems* +principle means that as long as something is manageable via the Kubernetes +Resource Model, it is manageable via Nephio. From 41fb7abce08504dbe664551d3a70b04a2ce6b097 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 5 Sep 2024 11:11:26 +0300 Subject: [PATCH 05/74] Correcting a typo in the contributors-guide folder name (#161) Signed-off-by: Gergely Csatari --- .../porch/{contribturos-guide => contributors-guide}/_index.md | 0 .../{contribturos-guide => contributors-guide}/dev-process.md | 0 .../environment-setup-vm.md | 0 .../environment-setup.md | 0 4 files changed, 0 insertions(+), 0 deletions(-) rename content/en/docs/porch/{contribturos-guide => contributors-guide}/_index.md (100%) rename content/en/docs/porch/{contribturos-guide => contributors-guide}/dev-process.md (100%) rename content/en/docs/porch/{contribturos-guide => contributors-guide}/environment-setup-vm.md (100%) rename content/en/docs/porch/{contribturos-guide => contributors-guide}/environment-setup.md (100%) diff --git a/content/en/docs/porch/contribturos-guide/_index.md b/content/en/docs/porch/contributors-guide/_index.md similarity index 100% rename from content/en/docs/porch/contribturos-guide/_index.md rename to content/en/docs/porch/contributors-guide/_index.md diff --git a/content/en/docs/porch/contribturos-guide/dev-process.md b/content/en/docs/porch/contributors-guide/dev-process.md similarity index 100% rename from content/en/docs/porch/contribturos-guide/dev-process.md rename to content/en/docs/porch/contributors-guide/dev-process.md diff --git a/content/en/docs/porch/contribturos-guide/environment-setup-vm.md b/content/en/docs/porch/contributors-guide/environment-setup-vm.md similarity index 100% rename from content/en/docs/porch/contribturos-guide/environment-setup-vm.md rename to content/en/docs/porch/contributors-guide/environment-setup-vm.md diff --git a/content/en/docs/porch/contribturos-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md similarity index 100% rename from content/en/docs/porch/contribturos-guide/environment-setup.md rename to content/en/docs/porch/contributors-guide/environment-setup.md From 5aa6a97d84dd419a29c84efa0b6e517d3517361b Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 5 Sep 2024 11:21:26 +0300 Subject: [PATCH 06/74] Adding offline search option using Lunr (#167) Signed-off-by: Gergely Csatari --- README.md | 2 -- config.toml | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index f2727ab0..8d59d017 100644 --- a/README.md +++ b/README.md @@ -131,5 +131,3 @@ Please use the documentation links below to learn more about Nephio, or check ou * [Developer Documentation](https://github.com/nephio-project/nephio) * [Developer Guide](https://docs.nephio.org/docs/guides/contributor-guides/) * [Project Resources](https://github.com/nephio-project/docs/blob/main/resources.md) - - diff --git a/config.toml b/config.toml index 7aeb1d62..7b53925b 100644 --- a/config.toml +++ b/config.toml @@ -116,7 +116,7 @@ params.search.algolia = false #Enable offline search with Lunr.js -offlineSearch = false +offlineSearch = true offlineSearchSummaryLength = 70 offlineSearchMaxResults = 10 From 8eb30c448a1d9f27e0c74c9f8b06a4a355971725 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 12 Sep 2024 11:38:09 +0300 Subject: [PATCH 07/74] Removal of reference to the VSCode workspace file (#170) It was removed in https://github.com/nephio-project/porch/pull/107 Signed-off-by: Gergely Csatari --- .../en/docs/porch/contributors-guide/_index.md | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/content/en/docs/porch/contributors-guide/_index.md b/content/en/docs/porch/contributors-guide/_index.md index 36205c97..349a0af9 100644 --- a/content/en/docs/porch/contributors-guide/_index.md +++ b/content/en/docs/porch/contributors-guide/_index.md @@ -17,10 +17,14 @@ make generate Porch comprises of several software components: -* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch extension apiserver -* [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of Porch `Repository` and `PackageRevision` custom resources. -* [apiserver](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST handlers, Porch `main` function -* [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - operations on package contents +* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch + extension apiserver +* [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of + Porch `Repository` and `PackageRevision` custom resources. +* [apiserver](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST + handlers, Porch `main` function +* [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - + operations on package contents * [func](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API * [repository](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package * [git](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository. @@ -108,6 +112,5 @@ then run test suite against the Porch instance. ## VSCode [VSCode](https://code.visualstudio.com/) works really well for editing and debugging. -Because Porch is comprises of multiple go modules, there is a pre-configured -multi-folder workspace in [porch.code-workspace](https://github.com/nephio-project/porch/blob/main/porch.code-workspace). -Open it in VSCode (File / Open Workspace from File) to use Workspace Folders. \ No newline at end of file +Just open VSCode from the root folder of the Porch repository and it will work fine. The folder contains the needed +configuration to Launch different functions of Proch. \ No newline at end of file From 2416f22d6a799896772c99c80f1e637c832d4343 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 12 Sep 2024 15:49:52 +0300 Subject: [PATCH 08/74] First try to integrate Vale Now without a token Signed-off-by: Gergely Csatari --- .github/.vale/alex/Ablist.yml | 248 ++++ .github/.vale/alex/Condescending.yml | 16 + .github/.vale/alex/Gendered.yml | 108 ++ .github/.vale/alex/LGBTQ.yml | 55 + .github/.vale/alex/Press.yml | 11 + .github/.vale/alex/ProfanityLikely.yml | 1289 +++++++++++++++++ .github/.vale/alex/ProfanityMaybe.yml | 282 ++++ .github/.vale/alex/ProfanityUnlikely.yml | 235 +++ .github/.vale/alex/README.md | 27 + .github/.vale/alex/Race.yml | 87 ++ .github/.vale/alex/Suicide.yml | 24 + .github/.vale/alex/meta.json | 4 + .../.vale/config/vocabularies/TODO/accept.txt | 65 + .github/.vale/proselint/Airlinese.yml | 8 + .github/.vale/proselint/AnimalLabels.yml | 48 + .github/.vale/proselint/Annotations.yml | 8 + .github/.vale/proselint/Apologizing.yml | 8 + .github/.vale/proselint/Archaisms.yml | 52 + .github/.vale/proselint/But.yml | 8 + .github/.vale/proselint/Cliches.yml | 782 ++++++++++ .github/.vale/proselint/CorporateSpeak.yml | 30 + .github/.vale/proselint/Currency.yml | 5 + .github/.vale/proselint/Cursing.yml | 15 + .github/.vale/proselint/DateCase.yml | 7 + .github/.vale/proselint/DateMidnight.yml | 7 + .github/.vale/proselint/DateRedundancy.yml | 10 + .github/.vale/proselint/DateSpacing.yml | 7 + .github/.vale/proselint/DenizenLabels.yml | 52 + .github/.vale/proselint/Diacritical.yml | 95 ++ .github/.vale/proselint/GenderBias.yml | 44 + .github/.vale/proselint/GroupTerms.yml | 39 + .github/.vale/proselint/Hedging.yml | 8 + .github/.vale/proselint/Hyperbole.yml | 6 + .github/.vale/proselint/Jargon.yml | 11 + .github/.vale/proselint/LGBTOffensive.yml | 13 + .github/.vale/proselint/LGBTTerms.yml | 15 + .github/.vale/proselint/Malapropisms.yml | 8 + .github/.vale/proselint/Needless.yml | 358 +++++ .github/.vale/proselint/Nonwords.yml | 38 + .github/.vale/proselint/Oxymorons.yml | 22 + .github/.vale/proselint/P-Value.yml | 6 + .github/.vale/proselint/RASSyndrome.yml | 30 + .github/.vale/proselint/README.md | 12 + .github/.vale/proselint/Skunked.yml | 13 + .github/.vale/proselint/Spelling.yml | 17 + .github/.vale/proselint/Typography.yml | 11 + .github/.vale/proselint/Uncomparables.yml | 50 + .github/.vale/proselint/Very.yml | 6 + .github/.vale/proselint/meta.json | 17 + .github/workflows/proofreading-vale.yml | 15 + .vale.ini | 5 + 51 files changed, 4337 insertions(+) create mode 100644 .github/.vale/alex/Ablist.yml create mode 100644 .github/.vale/alex/Condescending.yml create mode 100644 .github/.vale/alex/Gendered.yml create mode 100644 .github/.vale/alex/LGBTQ.yml create mode 100644 .github/.vale/alex/Press.yml create mode 100644 .github/.vale/alex/ProfanityLikely.yml create mode 100644 .github/.vale/alex/ProfanityMaybe.yml create mode 100644 .github/.vale/alex/ProfanityUnlikely.yml create mode 100644 .github/.vale/alex/README.md create mode 100644 .github/.vale/alex/Race.yml create mode 100644 .github/.vale/alex/Suicide.yml create mode 100644 .github/.vale/alex/meta.json create mode 100644 .github/.vale/config/vocabularies/TODO/accept.txt create mode 100644 .github/.vale/proselint/Airlinese.yml create mode 100644 .github/.vale/proselint/AnimalLabels.yml create mode 100644 .github/.vale/proselint/Annotations.yml create mode 100644 .github/.vale/proselint/Apologizing.yml create mode 100644 .github/.vale/proselint/Archaisms.yml create mode 100644 .github/.vale/proselint/But.yml create mode 100644 .github/.vale/proselint/Cliches.yml create mode 100644 .github/.vale/proselint/CorporateSpeak.yml create mode 100644 .github/.vale/proselint/Currency.yml create mode 100644 .github/.vale/proselint/Cursing.yml create mode 100644 .github/.vale/proselint/DateCase.yml create mode 100644 .github/.vale/proselint/DateMidnight.yml create mode 100644 .github/.vale/proselint/DateRedundancy.yml create mode 100644 .github/.vale/proselint/DateSpacing.yml create mode 100644 .github/.vale/proselint/DenizenLabels.yml create mode 100644 .github/.vale/proselint/Diacritical.yml create mode 100644 .github/.vale/proselint/GenderBias.yml create mode 100644 .github/.vale/proselint/GroupTerms.yml create mode 100644 .github/.vale/proselint/Hedging.yml create mode 100644 .github/.vale/proselint/Hyperbole.yml create mode 100644 .github/.vale/proselint/Jargon.yml create mode 100644 .github/.vale/proselint/LGBTOffensive.yml create mode 100644 .github/.vale/proselint/LGBTTerms.yml create mode 100644 .github/.vale/proselint/Malapropisms.yml create mode 100644 .github/.vale/proselint/Needless.yml create mode 100644 .github/.vale/proselint/Nonwords.yml create mode 100644 .github/.vale/proselint/Oxymorons.yml create mode 100644 .github/.vale/proselint/P-Value.yml create mode 100644 .github/.vale/proselint/RASSyndrome.yml create mode 100644 .github/.vale/proselint/README.md create mode 100644 .github/.vale/proselint/Skunked.yml create mode 100644 .github/.vale/proselint/Spelling.yml create mode 100644 .github/.vale/proselint/Typography.yml create mode 100644 .github/.vale/proselint/Uncomparables.yml create mode 100644 .github/.vale/proselint/Very.yml create mode 100644 .github/.vale/proselint/meta.json create mode 100644 .github/workflows/proofreading-vale.yml create mode 100644 .vale.ini diff --git a/.github/.vale/alex/Ablist.yml b/.github/.vale/alex/Ablist.yml new file mode 100644 index 00000000..cd6ddb5b --- /dev/null +++ b/.github/.vale/alex/Ablist.yml @@ -0,0 +1,248 @@ +--- +extends: substitution +message: When referring to a person, consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + ablebodied: non-disabled + addict: person with a drug addiction|person recovering from a drug addiction + addicts: people with a drug addiction|people recovering from a drug addiction + adhd: disorganized|distracted|energetic|hyperactive|impetuous|impulsive|inattentive|restless|unfocused + afflicted with MD: person who has muscular dystrophy + afflicted with a disability: has a disability|person with a disability|people with + disabilities + afflicted with a intellectual disability: person with an intellectual disability + afflicted with a polio: polio|person who had polio + afflicted with aids: person with AIDS + afflicted with an injury: sustain an injury|receive an injury + afflicted with disabilities: has a disability|person with a disability|people with + disabilities + afflicted with injuries: sustain injuries|receive injuries + afflicted with intellectual disabilities: person with an intellectual disability + afflicted with multiple sclerosis: person who has multiple sclerosis + afflicted with muscular dystrophy: person who has muscular dystrophy + afflicted with polio: polio|person who had polio + afflicted with psychosis: person with a psychotic condition|person with psychosis + afflicted with schizophrenia: person with schizophrenia + aids victim: person with AIDS + alcohol abuser: someone with an alcohol problem + alcoholic: someone with an alcohol problem + amputee: person with an amputation + anorexic: thin|slim + asylum: psychiatric hospital|mental health hospital + barren: empty|sterile|infertile + batshit: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of + mental illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + bedlam: chaos|hectic|pandemonium + binge: enthusiastic|spree + bipolar: fluctuating|person with bipolar disorder + birth defect: has a disability|person with a disability|people with disabilities + blind eye to: careless|heartless|indifferent|insensitive + blind to: careless|heartless|indifferent|insensitive + blinded by: careless|heartless|indifferent|insensitive + bony: thin|slim + bound to a wheelchair: uses a wheelchair + buckteeth: person with prominent teeth|prominent teeth + bucktoothed: person with prominent teeth|prominent teeth + challenged: has a disability|person with a disability|people with disabilities + cleftlipped: person with a cleft-lip and palate + confined to a wheelchair: uses a wheelchair + contard: disagreeable|uneducated|ignorant|naive|inconsiderate + crazy: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + cretin: creep|fool + cripple: person with a limp + crippled: person with a limp + daft: absurd|foolish + deaf and dumb: deaf + deaf ear to: careless|heartless|indifferent|insensitive + deaf to: careless|heartless|indifferent|insensitive + deafened by: careless|heartless|indifferent|insensitive + deafmute: deaf + delirious: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of + mental illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + demented: person with dementia + depressed: sad|blue|bummed out|person with seasonal affective disorder|person with + psychotic depression|person with postpartum depression + detox: treatment + detox center: treatment center + diffability: has a disability|person with a disability|people with disabilities + differently abled: has a disability|person with a disability|people with disabilities + disabled: turned off|has a disability|person with a disability|people with disabilities + downs syndrome: Down Syndrome + dumb: foolish|ludicrous|speechless|silent + dummy: test double|placeholder|fake|stub + dummyobject: test double|placeholder|fake|stub + dummyvalue: test double|placeholder|fake|stub + dummyvariable: test double|placeholder|fake|stub + dwarf: person with dwarfism|little person|little people|LP|person of short stature + dyslexic: person with dyslexia + epileptic: person with epilepsy + family burden: with family support needs + feeble minded: foolish|ludicrous|silly + feebleminded: foolish|ludicrous|silly + fucktard: disagreeable|uneducated|ignorant|naive|inconsiderate + gimp: person with a limp + handicapable: has a disability|person with a disability|people with disabilities + handicapped: person with a handicap|accessible + handicapped parking: accessible parking + hare lip: cleft-lip and palate + harelip: cleft-lip and palate + harelipped: person with a cleft-lip and palate + has intellectual issues: person with an intellectual disability + hearing impaired: hard of hearing|partially deaf|partial hearing loss|deaf + hearing impairment: hard of hearing|partially deaf|partial hearing loss|deaf + idiot: foolish|ludicrous|silly + imbecile: foolish|ludicrous|silly + infantile paralysis: polio|person who had polio + insane: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + insanely: incredibly + insanity: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of + mental illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + insomnia: restlessness|sleeplessness + insomniac: person who has insomnia + insomniacs: people who have insomnia + intellectually disabled: person with an intellectual disability + intellectually disabled people: people with intellectual disabilities + invalid: turned off|has a disability|person with a disability|people with disabilities + junkie: person with a drug addiction|person recovering from a drug addiction + junkies: people with a drug addiction|people recovering from a drug addiction + lame: boring|dull + learning disabled: person with learning disabilities + libtard: disagreeable|uneducated|ignorant|naive|inconsiderate + loony: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + loony bin: chaos|hectic|pandemonium + low iq: foolish|ludicrous|unintelligent + lunacy: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + lunatic: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of + mental illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + madhouse: chaos|hectic|pandemonium + maniac: fanatic|zealot|enthusiast + manic: person with schizophrenia + mental: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + mental case: rude|malicious|mean|disgusting|incredible|vile|person with symptoms + of mental illness|person with mental illness|person with symptoms of a mental + disorder|person with a mental disorder + mental defective: rude|malicious|mean|disgusting|incredible|vile|person with symptoms + of mental illness|person with mental illness|person with symptoms of a mental + disorder|person with a mental disorder + mentally ill: rude|malicious|mean|disgusting|incredible|vile|person with symptoms + of mental illness|person with mental illness|person with symptoms of a mental + disorder|person with a mental disorder + midget: person with dwarfism|little person|little people|LP|person of short stature + mongoloid: person with Down Syndrome + moron: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + moronic: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of + mental illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + multiple sclerosis victim: person who has multiple sclerosis + neurotic: has an anxiety disorder|obsessive|pedantic|niggly|picky + nuts: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + o.c.d: has an anxiety disorder|obsessive|pedantic|niggly|picky + o.c.d.: has an anxiety disorder|obsessive|pedantic|niggly|picky + ocd: has an anxiety disorder|obsessive|pedantic|niggly|picky + panic attack: fit of terror|scare + paraplegic: person with paraplegia + psycho: rude|malicious|mean|disgusting|incredible|vile|person with symptoms of mental + illness|person with mental illness|person with symptoms of a mental disorder|person + with a mental disorder + psychopathology: rude|malicious|mean|disgusting|incredible|vile|person with symptoms + of mental illness|person with mental illness|person with symptoms of a mental + disorder|person with a mental disorder + psychotic: person with a psychotic condition|person with psychosis + quadriplegic: person with quadriplegia + rehab: treatment + rehab center: treatment center + restricted to a wheelchair: uses a wheelchair + retard: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold + back + retarded: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold + back + retards: "sillies|dullards|people with developmental disabilities|people with Down\u2019\ + s Syndrome|delays|holds back" + sane: correct|adequate|sufficient|consistent|valid|coherent|sensible|reasonable + sanity check: check|assertion|validation|smoke test + schizo: person with schizophrenia + schizophrenic: person with schizophrenia + senile: person with dementia + short bus: silly|dullard|person with Down Syndrome|person with developmental disabilities|delay|hold + back + simpleton: foolish|ludicrous|unintelligent + small person: person with dwarfism|little person|little people|LP|person of short + stature + sociopath: person with a personality disorder|person with psychopathic personality + sociopaths: people with psychopathic personalities|people with a personality disorder + spastic: person with cerebral palsy|twitch|flinch + spaz: person with cerebral palsy|twitch|flinch|hectic + special: has a disability|person with a disability|people with disabilities + special needs: has a disability|person with a disability|people with disabilities + special olympians: athletes|Special Olympics athletes + special olympic athletes: athletes|Special Olympics athletes + specially abled: has a disability|person with a disability|people with disabilities + stammering: stuttering|disfluency of speech + stroke victim: individual who has had a stroke + stupid: foolish|ludicrous|unintelligent + stutterer: person who stutters + suffer from aids: person with AIDS + suffer from an injury: sustain an injury|receive an injury + suffer from injuries: sustain injuries|receive injuries + suffering from a disability: has a disability|person with a disability|people with + disabilities + suffering from a polio: polio|person who had polio + suffering from a stroke: individual who has had a stroke + suffering from aids: person with AIDS + suffering from an injury: sustain an injury|receive an injury + suffering from an intellectual disability: person with an intellectual disability + suffering from disabilities: has a disability|person with a disability|people with + disabilities + suffering from injuries: sustain injuries|receive injuries + suffering from intellectual disabilities: person with an intellectual disability + suffering from multiple sclerosis: person who has multiple sclerosis + suffering from polio: polio|person who had polio + suffering from psychosis: person with a psychotic condition|person with psychosis + suffering from schizophrenia: person with schizophrenia + suffers from MD: person who has muscular dystrophy + suffers from aids: person with AIDS + suffers from an injury: sustain an injury|receive an injury + suffers from disabilities: has a disability|person with a disability|people with + disabilities + suffers from injuries: sustain injuries|receive injuries + suffers from intellectual disabilities: person with an intellectual disability + suffers from multiple sclerosis: person who has multiple sclerosis + suffers from muscular dystrophy: person who has muscular dystrophy + suffers from polio: polio|person who had polio + suffers from psychosis: person with a psychotic condition|person with psychosis + suffers from schizophrenia: person with schizophrenia + tourettes disorder: Tourette syndrome + tourettes syndrome: Tourette syndrome + vertically challenged: person with dwarfism|little person|little people|LP|person + of short stature + victim of a stroke: individual who has had a stroke + victim of aids: person with AIDS + victim of an injury: sustain an injury|receive an injury + victim of injuries: sustain injuries|receive injuries + victim of multiple sclerosis: person who has multiple sclerosis + victim of polio: polio|person who had polio + victim of psychosis: person with a psychotic condition|person with psychosis + wacko: foolish|ludicrous|unintelligent + whacko: foolish|ludicrous|unintelligent + wheelchair bound: uses a wheelchair diff --git a/.github/.vale/alex/Condescending.yml b/.github/.vale/alex/Condescending.yml new file mode 100644 index 00000000..4283a336 --- /dev/null +++ b/.github/.vale/alex/Condescending.yml @@ -0,0 +1,16 @@ +--- +extends: existence +message: Using '%s' may come across as condescending. +link: https://css-tricks.com/words-avoid-educational-writing/ +level: error +ignorecase: true +tokens: + - obvious + - obviously + - simple + - simply + - easy + - easily + - of course + - clearly + - everyone knows diff --git a/.github/.vale/alex/Gendered.yml b/.github/.vale/alex/Gendered.yml new file mode 100644 index 00000000..c7b1f06b --- /dev/null +++ b/.github/.vale/alex/Gendered.yml @@ -0,0 +1,108 @@ +--- +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: warning +action: + name: replace +swap: + ancient man: ancient civilization|ancient people + authoress: author|writer + average housewife: average consumer|average household|average homemaker + average man: average person + average working man: average wage earner|average taxpayer + aviatrix: aviator + bitch: whine|complain|cry + bitching: whining|complaining|crying + brotherhood of man: the human family + calendar girl: model + call girl: escort|prostitute|sex worker + churchman: cleric|practicing Christian|pillar of the Church + english master: english coordinator|senior teacher of english + englishmen: the english + executrix: executor + father of *: founder of + fellowship: camaraderie|community|organization + founding father: the founders|founding leaders|forebears + frenchmen: french|the french + freshman: first-year student|fresher + freshwoman: first-year student|fresher + housemaid: house worker|domestic help + housewife: homemaker|homeworker + housewives: homemakers|homeworkers + industrial man: industrial civilization|industrial people + lady doctor: doctor + ladylike: courteous|cultured + leading lady: lead + like a man: resolutely|bravely + mad man: fanatic|zealot|enthusiast + mad men: fanatics|zealots|enthusiasts + madman: fanatic|zealot|enthusiast + madmen: fanatics|zealots|enthusiasts + maiden: virgin + maiden flight: first flight + maiden name: birth name + maiden race: first race + maiden speech: first speech + maiden voyage: first voyage + man a desk: staff a desk + man enough: strong enough + man hour: staff hour|hour of work + man hours: staff hours|hours of work|hours of labor|hours + man in the street: ordinary citizen|typical person|average person + man of action: dynamo + man of letters: scholar|writer|literary figure + man of the land: farmer|rural worker|grazier|landowner|rural community|country people|country + folk + man of the world: sophisticate + man sized task: a demanding task|a big job + man the booth: staff the booth + man the phones: answer the phones + manhour: staff hour|hour of work + manhours: staff hours|hours of work|hours of labor|hours + mankind: humankind + manmade: manufactured|artificial|synthetic|machine-made|constructed + manned: staffed|crewed|piloted + manpower: human resources|workforce|personnel|staff|labor|personnel|labor force|staffing|combat + personnel + mans best friend: a faithful dog + mansized task: a demanding task|a big job + master copy: pass key|original + master key: pass key|original + master of ceremonies: emcee|moderator|convenor + master plan: grand scheme|guiding principles + master the art: become skilled + masterful: skilled|authoritative|commanding + mastermind: genius|creator|instigator|oversee|launch|originate + masterpiece: "work of genius|chef d\u2019oeuvre" + masterplan: vision|comprehensive plan + masterstroke: trump card|stroke of genius + men of science: scientists + midwife: birthing nurse + miss\.: ms. + moan: whine|complain|cry + moaning: whining|complaining|crying + modern man: modern civilization|modern people + motherly: loving|warm|nurturing + mrs\.: ms. + no mans land: unoccupied territory|wasteland|deathtrap + office girls: administrative staff + oneupmanship: upstaging|competitiveness + poetess: poet + railwayman: railway worker + sportsmanlike: fair|sporting + sportsmanship: fairness|good humor|sense of fair play + statesman like: diplomatic + statesmanlike: diplomatic + stockman: cattle worker|farmhand|drover + tax man: tax commissioner|tax office|tax collector + tradesmans entrance: service entrance + unmanned: robotic|automated + usherette: usher + wife beater: tank top|sleeveless undershirt + wifebeater: tank top|sleeveless undershirt + woman lawyer: lawyer + woman painter: painter + working mother: wage or salary earning woman|two-income family + working wife: wage or salary earning woman|two-income family + workmanship: quality construction|expertise diff --git a/.github/.vale/alex/LGBTQ.yml b/.github/.vale/alex/LGBTQ.yml new file mode 100644 index 00000000..842a9c6f --- /dev/null +++ b/.github/.vale/alex/LGBTQ.yml @@ -0,0 +1,55 @@ +--- +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + bathroom bill: non-discrimination law|non-discrimination ordinance + bi: bisexual + biologically female: assigned female at birth|designated female at birth + biologically male: assigned male at birth|designated male at birth + born a man: assigned male at birth|designated male at birth + born a woman: assigned female at birth|designated female at birth + dyke: gay + fag: gay + faggot: gay + gay agenda: gay issues + gay lifestyle: gay lives|gay/lesbian lives + gay rights: equal rights|civil rights for gay people + gender pronoun: pronoun|pronouns + gender pronouns: pronoun|pronouns + genetically female: assigned female at birth|designated female at birth + genetically male: assigned male at birth|designated male at birth + hermaphrodite: person who is intersex|person|intersex person + hermaphroditic: intersex + heshe: transgender person|person + homo: gay + homosexual: gay|gay man|lesbian|gay person/people + homosexual agenda: gay issues + homosexual couple: couple + homosexual lifestyle: gay lives|gay/lesbian lives + homosexual marriage: gay marriage|same-sex marriage + homosexual relations: relationship + homosexual relationship: relationship + preferred pronoun: pronoun|pronouns + preferred pronouns: pronoun|pronouns + pseudo hermaphrodite: person who is intersex|person|intersex person + pseudo hermaphroditic: intersex + pseudohermaphrodite: person who is intersex|person|intersex person + pseudohermaphroditic: intersex + sex change: transition|gender confirmation surgery + sex change operation: sex reassignment surgery|gender confirmation surgery + sexchange: transition|gender confirmation surgery + sexual preference: sexual orientation|orientation + she male: transgender person|person + shehe: transgender person|person + shemale: transgender person|person + sodomite: gay + special rights: equal rights|civil rights for gay people + tranny: transgender + transgendered: transgender + transgenderism: being transgender|the movement for transgender equality + transgenders: transgender people + transvestite: cross-dresser diff --git a/.github/.vale/alex/Press.yml b/.github/.vale/alex/Press.yml new file mode 100644 index 00000000..06991dbf --- /dev/null +++ b/.github/.vale/alex/Press.yml @@ -0,0 +1,11 @@ +--- +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + islamist: muslim|person of Islamic faith|fanatic|zealot|follower of islam|follower + of the islamic faith + islamists: muslims|people of Islamic faith|fanatics|zealots diff --git a/.github/.vale/alex/ProfanityLikely.yml b/.github/.vale/alex/ProfanityLikely.yml new file mode 100644 index 00000000..1c03e198 --- /dev/null +++ b/.github/.vale/alex/ProfanityLikely.yml @@ -0,0 +1,1289 @@ +extends: existence +message: Don't use '%s', it’s profane. +level: warning +ignorecase: true +tokens: + - abeed + - africoon + - alligator bait + - alligatorbait + - analannie + - arabush + - arabushs + - argie + - armo + - armos + - arse + - arsehole + - ass + - assbagger + - assblaster + - assclown + - asscowboy + - asses + - assfuck + - assfucker + - asshat + - asshole + - assholes + - asshore + - assjockey + - asskiss + - asskisser + - assklown + - asslick + - asslicker + - asslover + - assman + - assmonkey + - assmunch + - assmuncher + - asspacker + - asspirate + - asspuppies + - assranger + - asswhore + - asswipe + - backdoorman + - badfuck + - balllicker + - barelylegal + - barf + - barface + - barfface + - bazongas + - bazooms + - beanbag + - beanbags + - beaner + - beaners + - beaney + - beaneys + - beatoff + - beatyourmeat + - biatch + - bigass + - bigbastard + - bigbutt + - bitcher + - bitches + - bitchez + - bitchin + - bitching + - bitchslap + - bitchy + - biteme + - blowjob + - bluegum + - bluegums + - boang + - boche + - boches + - bogan + - bohunk + - bollick + - bollock + - bollocks + - bong + - boob + - boobies + - boobs + - booby + - boody + - boong + - boonga + - boongas + - boongs + - boonie + - boonies + - bootlip + - bootlips + - booty + - bootycall + - bosch + - bosche + - bosches + - boschs + - brea5t + - breastjob + - breastlover + - breastman + - buddhahead + - buddhaheads + - buffies + - bugger + - buggered + - buggery + - bule + - bules + - bullcrap + - bulldike + - bulldyke + - bullshit + - bumblefuck + - bumfuck + - bung + - bunga + - bungas + - bunghole + - "burr head" + - "burr heads" + - burrhead + - burrheads + - butchbabes + - butchdike + - butchdyke + - buttbang + - buttface + - buttfuck + - buttfucker + - buttfuckers + - butthead + - buttman + - buttmunch + - buttmuncher + - buttpirate + - buttplug + - buttstain + - byatch + - cacker + - "camel jockey" + - "camel jockeys" + - cameljockey + - cameltoe + - carpetmuncher + - carruth + - chav + - "cheese eating surrender monkey" + - "cheese eating surrender monkies" + - "cheeseeating surrender monkey" + - "cheeseeating surrender monkies" + - cheesehead + - cheeseheads + - cherrypopper + - chickslick + - "china swede" + - "china swedes" + - chinaman + - chinamen + - chinaswede + - chinaswedes + - "ching chong" + - "ching chongs" + - chingchong + - chingchongs + - chink + - chinks + - chinky + - choad + - chode + - chonkies + - chonky + - chonkys + - "christ killer" + - "christ killers" + - chug + - chugs + - chunger + - chungers + - chunkies + - chunky + - chunkys + - clamdigger + - clamdiver + - clansman + - clansmen + - clanswoman + - clanswomen + - clit + - clitoris + - clogwog + - cockblock + - cockblocker + - cockcowboy + - cockfight + - cockhead + - cockknob + - cocklicker + - cocklover + - cocknob + - cockqueen + - cockrider + - cocksman + - cocksmith + - cocksmoker + - cocksucer + - cocksuck + - cocksucked + - cocksucker + - cocksucking + - cocktease + - cocky + - cohee + - commie + - coolie + - coolies + - cooly + - coon + - "coon ass" + - "coon asses" + - coonass + - coonasses + - coondog + - coons + - cornhole + - cracka + - crackwhore + - crap + - crapola + - crapper + - crappy + - crotchjockey + - crotchmonkey + - crotchrot + - cum + - cumbubble + - cumfest + - cumjockey + - cumm + - cummer + - cumming + - cummings + - cumquat + - cumqueen + - cumshot + - cunn + - cunntt + - cunt + - cunteyed + - cuntfuck + - cuntfucker + - cuntlick + - cuntlicker + - cuntlicking + - cuntsucker + - "curry muncher" + - "curry munchers" + - currymuncher + - currymunchers + - cushi + - cushis + - cyberslimer + - dago + - dagos + - dahmer + - dammit + - damnit + - darkey + - darkeys + - darkie + - darkies + - darky + - datnigga + - deapthroat + - deepthroat + - dego + - degos + - "diaper head" + - "diaper heads" + - diaperhead + - diaperheads + - dickbrain + - dickforbrains + - dickhead + - dickless + - dicklick + - dicklicker + - dickman + - dickwad + - dickweed + - diddle + - dingleberry + - dink + - dinks + - dipshit + - dipstick + - dix + - dixiedike + - dixiedyke + - doggiestyle + - doggystyle + - dong + - doodoo + - dope + - "dot head" + - "dot heads" + - dothead + - dotheads + - dragqueen + - dragqween + - dripdick + - dumb + - dumbass + - dumbbitch + - dumbfuck + - "dune coon" + - "dune coons" + - dyefly + - easyslut + - eatballs + - eatme + - eatpussy + - "eight ball" + - "eight balls" + - ero + - esqua + - evl + - exkwew + - facefucker + - faeces + - fagging + - faggot + - fagot + - fannyfucker + - farty + - fastfuck + - fatah + - fatass + - fatfuck + - fatfucker + - fatso + - fckcum + - felch + - felcher + - felching + - fellatio + - feltch + - feltcher + - feltching + - fingerfuck + - fingerfucked + - fingerfucker + - fingerfuckers + - fingerfucking + - fister + - fistfuck + - fistfucked + - fistfucker + - fistfucking + - fisting + - flange + - floo + - flydie + - flydye + - fok + - footfuck + - footfucker + - footlicker + - footstar + - forni + - fornicate + - foursome + - fourtwenty + - fraud + - freakfuck + - freakyfucker + - freefuck + - fu + - fubar + - fuc + - fucck + - fuck + - fucka + - fuckable + - fuckbag + - fuckbook + - fuckbuddy + - fucked + - fuckedup + - fucker + - fuckers + - fuckface + - fuckfest + - fuckfreak + - fuckfriend + - fuckhead + - fuckher + - fuckin + - fuckina + - fucking + - fuckingbitch + - fuckinnuts + - fuckinright + - fuckit + - fuckknob + - fuckme + - fuckmehard + - fuckmonkey + - fuckoff + - fuckpig + - fucks + - fucktard + - fuckwhore + - fuckyou + - fudgepacker + - fugly + - fuk + - fuks + - funeral + - funfuck + - fungus + - fuuck + - gables + - gangbang + - gangbanged + - gangbanger + - gangsta + - "gator bait" + - gatorbait + - gaymuthafuckinwhore + - gaysex + - geez + - geezer + - geni + - getiton + - ginzo + - ginzos + - gipp + - gippo + - gippos + - gipps + - givehead + - glazeddonut + - godammit + - goddamit + - goddammit + - goddamn + - goddamned + - goddamnes + - goddamnit + - goddamnmuthafucker + - goldenshower + - golliwog + - golliwogs + - gonorrehea + - gonzagas + - gook + - "gook eye" + - "gook eyes" + - gookeye + - gookeyes + - gookies + - gooks + - gooky + - gora + - goras + - gotohell + - greaseball + - greaseballs + - greaser + - greasers + - gringo + - gringos + - groe + - groid + - groids + - gubba + - gubbas + - gubs + - gummer + - gwailo + - gwailos + - gweilo + - gweilos + - gyopo + - gyopos + - gyp + - gyped + - gypo + - gypos + - gypp + - gypped + - gyppie + - gyppies + - gyppo + - gyppos + - gyppy + - gyppys + - gypsies + - gypsy + - gypsys + - hadji + - hadjis + - hairyback + - hairybacks + - haji + - hajis + - hajji + - hajjis + - "half breed" + - "half caste" + - halfbreed + - halfcaste + - hamas + - handjob + - haole + - haoles + - hapa + - hardon + - headfuck + - headlights + - hebe + - hebephila + - hebephile + - hebephiles + - hebephilia + - hebephilic + - hebes + - heeb + - heebs + - hillbillies + - hillbilly + - hindoo + - hiscock + - hitler + - hitlerism + - hitlerist + - ho + - hobo + - hodgie + - hoes + - holestuffer + - homo + - homobangers + - honger + - honk + - honkers + - honkey + - honkeys + - honkie + - honkies + - honky + - hooker + - hookers + - hooters + - hore + - hori + - horis + - hork + - horney + - horniest + - horseshit + - hosejob + - hoser + - hotdamn + - hotpussy + - hottotrot + - hussy + - hymie + - hymies + - iblowu + - idiot + - ikeymo + - ikeymos + - ikwe + - indons + - injun + - injuns + - insest + - intheass + - inthebuff + - jackass + - jackoff + - jackshit + - jacktheripper + - jap + - japcrap + - japie + - japies + - japs + - jebus + - jeez + - jerkoff + - jewboy + - jewed + - jewess + - jig + - jiga + - jigaboo + - jigaboos + - jigarooni + - jigaroonis + - jigg + - jigga + - jiggabo + - jiggabos + - jiggas + - jigger + - jiggers + - jiggs + - jiggy + - jigs + - jijjiboo + - jijjiboos + - jimfish + - jism + - jiz + - jizim + - jizjuice + - jizm + - jizz + - jizzim + - jizzum + - juggalo + - "jungle bunnies" + - "jungle bunny" + - junglebunny + - kacap + - kacapas + - kacaps + - kaffer + - kaffir + - kaffre + - kafir + - kanake + - katsap + - katsaps + - khokhol + - khokhols + - kigger + - kike + - kikes + - kimchis + - kissass + - kkk + - klansman + - klansmen + - klanswoman + - klanswomen + - kondum + - koon + - krap + - krappy + - krauts + - kuffar + - kum + - kumbubble + - kumbullbe + - kummer + - kumming + - kumquat + - kums + - kunilingus + - kunnilingus + - kunt + - kushi + - kushis + - kwa + - "kwai lo" + - "kwai los" + - ky + - kyke + - kykes + - kyopo + - kyopos + - lebo + - lebos + - lesbain + - lesbayn + - lesbian + - lesbin + - lesbo + - lez + - lezbe + - lezbefriends + - lezbo + - lezz + - lezzo + - lickme + - limey + - limpdick + - limy + - livesex + - loadedgun + - looser + - loser + - lovebone + - lovegoo + - lovegun + - lovejuice + - lovemuscle + - lovepistol + - loverocket + - lowlife + - lsd + - lubejob + - lubra + - luckycammeltoe + - lugan + - lugans + - mabuno + - mabunos + - macaca + - macacas + - magicwand + - mahbuno + - mahbunos + - mams + - manhater + - manpaste + - mastabate + - mastabater + - masterbate + - masterblaster + - mastrabator + - masturbate + - masturbating + - mattressprincess + - "mau mau" + - "mau maus" + - maumau + - maumaus + - meatbeatter + - meatrack + - mgger + - mggor + - mickeyfinn + - milf + - mockey + - mockie + - mocky + - mofo + - moky + - moneyshot + - "moon cricket" + - "moon crickets" + - mooncricket + - mooncrickets + - moron + - moskal + - moskals + - moslem + - mosshead + - mothafuck + - mothafucka + - mothafuckaz + - mothafucked + - mothafucker + - mothafuckin + - mothafucking + - mothafuckings + - motherfuck + - motherfucked + - motherfucker + - motherfuckin + - motherfucking + - motherfuckings + - motherlovebone + - muff + - muffdive + - muffdiver + - muffindiver + - mufflikcer + - mulatto + - muncher + - munt + - mzungu + - mzungus + - nastybitch + - nastyho + - nastyslut + - nastywhore + - negres + - negress + - negro + - negroes + - negroid + - negros + - nig + - nigar + - nigars + - niger + - nigerian + - nigerians + - nigers + - nigette + - nigettes + - nigg + - nigga + - niggah + - niggahs + - niggar + - niggaracci + - niggard + - niggarded + - niggarding + - niggardliness + - niggardlinesss + - niggardly + - niggards + - niggars + - niggas + - niggaz + - nigger + - niggerhead + - niggerhole + - niggers + - niggle + - niggled + - niggles + - niggling + - nigglings + - niggor + - niggress + - niggresses + - nigguh + - nigguhs + - niggur + - niggurs + - niglet + - nignog + - nigor + - nigors + - nigr + - nigra + - nigras + - nigre + - nigres + - nigress + - nigs + - nip + - nittit + - nlgger + - nlggor + - nofuckingway + - nookey + - nookie + - noonan + - nudger + - nutfucker + - ontherag + - orga + - orgasim + - paki + - pakis + - palesimian + - "pancake face" + - "pancake faces" + - pansies + - pansy + - panti + - payo + - peckerwood + - pedo + - peehole + - peepshpw + - peni5 + - perv + - phuk + - phuked + - phuking + - phukked + - phukking + - phungky + - phuq + - pi55 + - picaninny + - piccaninny + - pickaninnies + - pickaninny + - piefke + - piefkes + - piker + - pikey + - piky + - pimp + - pimped + - pimper + - pimpjuic + - pimpjuice + - pimpsimp + - pindick + - piss + - pissed + - pisser + - pisses + - pisshead + - pissin + - pissing + - pissoff + - pocha + - pochas + - pocho + - pochos + - pocketpool + - pohm + - pohms + - polack + - polacks + - pollock + - pollocks + - pom + - pommie + - "pommie grant" + - "pommie grants" + - pommies + - pommy + - poms + - poo + - poon + - poontang + - poop + - pooper + - pooperscooper + - pooping + - poorwhitetrash + - popimp + - "porch monkey" + - "porch monkies" + - porchmonkey + - pornking + - porno + - pornography + - pornprincess + - "prairie nigger" + - "prairie niggers" + - premature + - pric + - prick + - prickhead + - pu55i + - pu55y + - pubiclice + - pud + - pudboy + - pudd + - puddboy + - puke + - puntang + - purinapricness + - puss + - pussie + - pussies + - pussyeater + - pussyfucker + - pussylicker + - pussylips + - pussylover + - pussypounder + - pusy + - quashie + - queef + - quickie + - quim + - ra8s + - raghead + - ragheads + - raper + - rearend + - rearentry + - redleg + - redlegs + - redneck + - rednecks + - redskin + - redskins + - reefer + - reestie + - rere + - retard + - retarded + - ribbed + - rigger + - rimjob + - rimming + - "round eyes" + - roundeye + - russki + - russkie + - sadis + - sadom + - sambo + - sambos + - samckdaddy + - "sand nigger" + - "sand niggers" + - sandm + - sandnigger + - satan + - scag + - scallywag + - schlong + - schvartse + - schvartsen + - schwartze + - schwartzen + - screwyou + - seppo + - seppos + - sexed + - sexfarm + - sexhound + - sexhouse + - sexing + - sexkitten + - sexpot + - sexslave + - sextogo + - sexwhore + - sexymoma + - sexyslim + - shaggin + - shagging + - shat + - shav + - shawtypimp + - sheeney + - shhit + - shiksa + - shinola + - shit + - shitcan + - shitdick + - shite + - shiteater + - shited + - shitface + - shitfaced + - shitfit + - shitforbrains + - shitfuck + - shitfucker + - shitfull + - shithapens + - shithappens + - shithead + - shithouse + - shiting + - shitlist + - shitola + - shitoutofluck + - shits + - shitstain + - shitted + - shitter + - shitting + - shitty + - shortfuck + - shylock + - shylocks + - sissy + - sixsixsix + - sixtynine + - sixtyniner + - skank + - skankbitch + - skankfuck + - skankwhore + - skanky + - skankybitch + - skankywhore + - skinflute + - skum + - skumbag + - skwa + - skwe + - slant + - slanteye + - slanty + - slapper + - slave + - slavedriver + - sleezebag + - sleezeball + - slideitin + - slimeball + - slimebucket + - slopehead + - slopeheads + - sloper + - slopers + - slopes + - slopey + - slopeys + - slopies + - slopy + - slut + - sluts + - slutt + - slutting + - slutty + - slutwear + - slutwhore + - smackthemonkey + - smut + - snatchpatch + - snowback + - snownigger + - sodomise + - sodomize + - sodomy + - sonofabitch + - sonofbitch + - sooties + - sooty + - spaghettibender + - spaghettinigger + - spankthemonkey + - spearchucker + - spearchuckers + - spermacide + - spermbag + - spermhearder + - spermherder + - spic + - spick + - spicks + - spics + - spig + - spigotty + - spik + - spit + - spitter + - splittail + - spooge + - spreadeagle + - spunk + - spunky + - sqeh + - squa + - squarehead + - squareheads + - squaw + - squinty + - stringer + - stripclub + - stuinties + - stupid + - stupidfuck + - stupidfucker + - suckdick + - sucker + - suckme + - suckmyass + - suckmydick + - suckmytit + - suckoff + - swallower + - swalow + - "swamp guinea" + - "swamp guineas" + - tacohead + - tacoheads + - taff + - tang + - "tar babies" + - "tar baby" + - tarbaby + - tard + - teste + - thicklip + - thicklips + - thirdeye + - thirdleg + - threeway + - "timber nigger" + - "timber niggers" + - timbernigger + - tinker + - tinkers + - titbitnipply + - titfuck + - titfucker + - titfuckin + - titjob + - titlicker + - titlover + - tits + - tittie + - titties + - titty + - tongethruster + - tongue + - tonguethrust + - tonguetramp + - tortur + - tosser + - "towel head" + - "towel heads" + - towelhead + - trailertrash + - trannie + - tranny + - transvestite + - triplex + - tuckahoe + - tunneloflove + - turd + - turnon + - twat + - twink + - twinkie + - twobitwhore + - uck + - ukrop + - "uncle tom" + - unfuckable + - upskirt + - uptheass + - upthebutt + - usama + - vibr + - vibrater + - vomit + - wab + - wank + - wanker + - wanking + - waysted + - weenie + - weewee + - welcher + - welfare + - wetb + - wetback + - wetbacks + - wetspot + - whacker + - whash + - whigger + - whiggers + - whiskeydick + - whiskydick + - "white trash" + - whitenigger + - whitetrash + - whitey + - whiteys + - whities + - whiz + - whop + - whore + - whorefucker + - whorehouse + - wigga + - wiggas + - wigger + - wiggers + - willie + - williewanker + - wn + - wog + - wogs + - womens + - wop + - wtf + - wuss + - wuzzie + - xkwe + - yank + - yanks + - yarpie + - yarpies + - yellowman + - yid + - yids + - zigabo + - zigabos + - zipperhead + - zipperheads diff --git a/.github/.vale/alex/ProfanityMaybe.yml b/.github/.vale/alex/ProfanityMaybe.yml new file mode 100644 index 00000000..e889b3a3 --- /dev/null +++ b/.github/.vale/alex/ProfanityMaybe.yml @@ -0,0 +1,282 @@ +extends: existence +message: Reconsider using '%s', it may be profane. +level: warning +ignorecase: true +tokens: + - abbo + - abid + - abo + - abortion + - abuse + - addict + - addicts + - alla + - anal + - analsex + - anus + - areola + - athletesfoot + - attack + - australian + - babe + - banging + - bastard + - beastality + - beastial + - beastiality + - bicurious + - bitch + - bitches + - blackman + - blacks + - bondage + - boob + - boobs + - "bounty bar" + - "bounty bars" + - bountybar + - brothel + - buttplug + - clit + - clitoris + - cocaine + - cock + - coitus + - condom + - copulate + - cra5h + - crack + - cracker + - crackpipe + - crotch + - cunilingus + - cunillingus + - cybersex + - damn + - damnation + - defecate + - demon + - devil + - devilworshipper + - dick + - dike + - dildo + - drug + - drunk + - drunken + - dyke + - ejaculate + - ejaculated + - ejaculating + - ejaculation + - enema + - erection + - excrement + - fag + - fart + - farted + - farting + - feces + - felatio + - fetish + - fingerfood + - flasher + - flatulence + - fondle + - footaction + - foreskin + - foursome + - fourtwenty + - fruitcake + - gable + - genital + - gob + - god + - gonzagas + - goy + - goyim + - groe + - gross + - grostulation + - gub + - guinea + - guineas + - guizi + - hamas + - hebephila + - hebephile + - hebephiles + - hebephilia + - hebephilic + - heroin + - herpes + - hiv + - homicide + - horney + - ike + - ikes + - ikey + - illegals + - incest + - intercourse + - interracial + - italiano + - jerries + - jerry + - jesus + - jesuschrist + - jihad + - kink + - kinky + - knockers + - kock + - kotex + - kraut + - ky + - lactate + - lapdance + - libido + - licker + - liquor + - lolita + - lsd + - lynch + - mafia + - marijuana + - meth + - mick + - molest + - molestation + - molester + - molestor + - murder + - narcotic + - nazi + - necro + - nigerian + - nigerians + - nipple + - nipplering + - nook + - nooner + - nude + - nuke + - nymph + - oral + - orgasm + - orgies + - orgy + - paddy + - paederastic + - paederasts + - paederasty + - pearlnecklace + - peck + - pecker + - pederastic + - pederasts + - pederasty + - pedophile + - pedophiles + - pedophilia + - pedophilic + - pee + - peepshow + - pendy + - penetration + - penile + - penis + - penises + - penthouse + - phonesex + - pistol + - pixie + - pixy + - playboy + - playgirl + - porn + - pornflick + - porno + - pornography + - prostitute + - protestant + - pube + - pubic + - pussy + - pussycat + - queer + - racist + - radical + - radicals + - randy + - rape + - raped + - raper + - rapist + - rectum + - ribbed + - satan + - scag + - scat + - screw + - scrotum + - scum + - semen + - septic + - septics + - sex + - sexhouse + - sextoy + - sextoys + - sexual + - sexually + - sexy + - shag + - shinola + - shit + - slaughter + - smack + - snatch + - sniggers + - sodom + - sodomite + - spade + - spank + - sperm + - stagg + - stiffy + - strapon + - stroking + - suck + - suicide + - swallow + - swastika + - syphilis + - tantra + - teat + - terrorist + - testicle + - testicles + - threesome + - tinkle + - tit + - tits + - tnt + - torture + - tramp + - trap + - trisexual + - trots + - turd + - uterus + - vagina + - vaginal + - vibrator + - vulva + - whit + - whites + - willy + - xtc + - xxx + - yankee + - yankees \ No newline at end of file diff --git a/.github/.vale/alex/ProfanityUnlikely.yml b/.github/.vale/alex/ProfanityUnlikely.yml new file mode 100644 index 00000000..f69b619b --- /dev/null +++ b/.github/.vale/alex/ProfanityUnlikely.yml @@ -0,0 +1,235 @@ +extends: existence +message: Be careful with '%s', it’s profane in some cases. +level: warning +ignorecase: true +tokens: + - adult + - africa + - allah + - amateur + - angie + - angry + - arab + - arabs + - aroused + - assassin + - assassinate + - assassination + - assault + - attack + - babies + - backdoor + - backseat + - banana + - bananas + - baptist + - bast + - beast + - beaver + - bi + - bigger + - bisexual + - blackout + - blind + - blow + - bomb + - bombers + - bombing + - bombs + - bomd + - boom + - bosch + - bra + - breast + - brownie + - brownies + - buffy + - burn + - butt + - cancer + - catholic + - catholics + - cemetery + - childrens + - chin + - christ + - christian + - church + - cigarette + - cigs + - cocktail + - coconut + - coconuts + - color + - colored + - coloured + - communist + - conservative + - conspiracy + - corruption + - crabs + - crash + - creamy + - criminal + - criminals + - dead + - death + - deposit + - desire + - destroy + - deth + - die + - died + - dies + - dirty + - disease + - diseases + - disturbed + - doom + - ecstacy + - enemy + - erect + - escort + - ethiopian + - ethnic + - executioner + - explosion + - failed + - failure + - fairies + - fairy + - faith + - fat + - fear + - fight + - filipina + - filipino + - fire + - firing + - fore + - fraud + - funeral + - fungus + - gay + - gin + - girls + - gun + - harder + - harem + - headlights + - hell + - henhouse + - heterosexual + - hijack + - hijacker + - hijacking + - hole + - honk + - hook + - horn + - hostage + - hummer + - hun + - huns + - husky + - hustler + - illegal + - israel + - israeli + - israels + - itch + - jade + - jerry + - jew + - jewish + - joint + - jugs + - kid + - kill + - killed + - killer + - killing + - kills + - kimchi + - laid + - latin + - lesbian + - liberal + - lies + - lingerie + - lotion + - lucifer + - mad + - mideast + - minority + - moles + - mormon + - muslim + - naked + - nasty + - niger + - niggardly + - oreo + - oreos + - osama + - palestinian + - panties + - penthouse + - period + - pot + - poverty + - premature + - primetime + - propaganda + - que + - rabbi + - racial + - redlight + - refugee + - reject + - remains + - republican + - roach + - robber + - rump + - servant + - shoot + - shooting + - showtime + - sick + - slant + - slav + - slime + - slope + - slopes + - snigger + - sniggered + - sniggering + - sniggers + - sniper + - snot + - sob + - sos + - soviet + - spa + - stroke + - sweetness + - taboo + - tampon + - terror + - toilet + - tongue + - transexual + - transsexual + - trojan + - uk + - urinary + - urinate + - urine + - vatican + - vietcong + - violence + - virgin + - weapon + - whiskey + - womens diff --git a/.github/.vale/alex/README.md b/.github/.vale/alex/README.md new file mode 100644 index 00000000..0185d0e3 --- /dev/null +++ b/.github/.vale/alex/README.md @@ -0,0 +1,27 @@ +Based on [alex](https://github.com/get-alex/alex). + +> Catch insensitive, inconsiderate writing + +``` +(The MIT License) + +Copyright (c) 2015 Titus Wormer + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. +``` diff --git a/.github/.vale/alex/Race.yml b/.github/.vale/alex/Race.yml new file mode 100644 index 00000000..9979c0b2 --- /dev/null +++ b/.github/.vale/alex/Race.yml @@ -0,0 +1,87 @@ +--- +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + Gipsy: Nomad|Traveler|Roma|Romani + Indian country: enemy territory + animal spirit: favorite|inspiration|personal interest|personality type + black list: blocklist|wronglist|banlist|deny list + blacklist: blocklist|wronglist|banlist|deny list + blacklisted: blocklisted|wronglisted|banlisted|deny-listed + blacklisting: blocklisting|wronglisting|banlisting|deny-listing + bugreport: bug report|snapshot + circle the wagons: defend + dream catcher: favorite|inspiration|personal interest|personality type + eskimo: Inuit + eskimos: Inuits + ghetto: projects|urban + goy: a person who is not Jewish|not Jewish + goyim: a person who is not Jewish|not Jewish + goyum: a person who is not Jewish|not Jewish + grandfather clause: legacy policy|legacy clause|deprecation policy + grandfather policy: legacy policy|legacy clause|deprecation policy + grandfathered: deprecated + grandfathering: deprecate + gyp: Nomad|Traveler|Roma|Romani + gyppo: Nomad|Traveler|Roma|Romani + gypsy: Nomad|Traveler|Roma|Romani + hymie: Jewish person + indian give: "go back on one\u2019s offer" + indian giver: "go back on one\u2019s offer" + japs: Japanese person|Japanese people + jump the reservation: disobey|endure|object to|oppose|resist + latina: Latinx + latino: Latinx + long time no hear: "I haven\u2019t seen you in a long time|it\u2019s been a long\ + \ time" + long time no see: "I haven\u2019t seen you in a long time|it\u2019s been a long\ + \ time" + master: primary|hub|reference + masters: primaries|hubs|references + mexican: Latinx + natives are becoming restless: dissatisfied|frustrated + natives are getting restless: dissatisfied|frustrated + natives are growing restless: dissatisfied|frustrated + natives are restless: dissatisfied|frustrated + non white: person of color|people of color + nonwhite: person of color|people of color + off reserve: disobey|endure|object to|oppose|resist + off the reservation: disobey|endure|object to|oppose|resist + on the warpath: defend + oriental: Asian person + orientals: Asian people + pinays: Filipinos|Filipino people + pinoys: Filipinos|Filipino people + pocahontas: Native American + pow wow: conference|gathering|meeting + powwow: conference|gathering|meeting + primitive: simple|indigenous|hunter-gatherer + red indian: Native American + red indians: Native American People + redskin: Native American + redskins: Native American People + sand niggers: Arabs|Middle Eastern People + savage: simple|indigenous|hunter-gatherer + shlomo: Jewish person + shyster: Jewish person + sophisticated culture: complex culture + sophisticated technology: complex technology + spade: a Black person + spirit animal: favorite|inspiration|personal interest|personality type + stone age: simple|indigenous|hunter-gatherer + too many chiefs: too many chefs in the kitchen|too many cooks spoil the broth + totem: favorite|inspiration|personal interest|personality type + towel heads: Arabs|Middle Eastern People + tribe: society|community + white list: passlist|alrightlist|safelist|allow list + white space: space|blank + white spaces: space|blank + whitelist: passlist|alrightlist|safelist|allow list + whitelisted: passlisted|alrightlisted|safelisted|allow-listed + whitelisting: passlisting|alrightlisting|safelisting|allow-listing + whitespace: space|blank + whitespaces: space|blank diff --git a/.github/.vale/alex/Suicide.yml b/.github/.vale/alex/Suicide.yml new file mode 100644 index 00000000..3dfd3e33 --- /dev/null +++ b/.github/.vale/alex/Suicide.yml @@ -0,0 +1,24 @@ +--- +extends: substitution +message: When referring to a person, consider using '%s' instead of '%s'. +ignorecase: true +level: warning +action: + name: replace +swap: + commit suicide: die by suicide + committed suicide: died by suicide + complete suicide: die by suicide + completed suicide: died by suicide + epidemic of suicides: rise in suicides + failed attempt: suicide attempt|attempted suicide + failed suicide: suicide attempt|attempted suicide + hang: the app froze|the app stopped responding|the app stopped responding to events|the + app became unresponsive + hanged: the app froze|the app stopped responding|the app stopped responding to events|the + app became unresponsive + successful suicide: die by suicide + suicide epidemic: rise in suicides + suicide failure: suicide attempt|attempted suicide + suicide note: a note from the deceased + suicide pact: rise in suicides diff --git a/.github/.vale/alex/meta.json b/.github/.vale/alex/meta.json new file mode 100644 index 00000000..3db4c282 --- /dev/null +++ b/.github/.vale/alex/meta.json @@ -0,0 +1,4 @@ +{ + "feed": "https://github.com/errata-ai/alex/releases.atom", + "vale_version": ">=1.0.0" +} \ No newline at end of file diff --git a/.github/.vale/config/vocabularies/TODO/accept.txt b/.github/.vale/config/vocabularies/TODO/accept.txt new file mode 100644 index 00000000..5b0b462d --- /dev/null +++ b/.github/.vale/config/vocabularies/TODO/accept.txt @@ -0,0 +1,65 @@ +# Accepted words (other acronyms must be explained) +CEOs? +CFOs? +InnerSource +NGOs? +OSPOs? +SBOMs? +TODO +Whitepaper +deliverables +libre + +# Author names +Alin +Aniszczyk +Annania +Ashish +Bogaard +Brasseur +Chitale +Coughlan +Csatari +Fukuchi +Gergely +Hendriks +Hiro +Hoving +Ibrahim +Ildiko +Jeroen +Jerpelea +Jiri +Khalaf +Khalil +Koymans +Kuwata +Lieggi +Maltzhan +Marek +Marz +Masae +Masayuki +Melaku +Moffat +Remy +Saebi +Scheerder +Seo +Shida +Shilla +Supriya +Takanori +Ulises +Vancsa +Xie +Yehuda +Yeon + +# Company names +Autodesk +Comcast +Qiita +Synopsys +Uber +VMware diff --git a/.github/.vale/proselint/Airlinese.yml b/.github/.vale/proselint/Airlinese.yml new file mode 100644 index 00000000..a6ae9c19 --- /dev/null +++ b/.github/.vale/proselint/Airlinese.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' is airlinese." +ignorecase: true +level: error +tokens: + - enplan(?:e|ed|ing|ement) + - deplan(?:e|ed|ing|ement) + - taking off momentarily diff --git a/.github/.vale/proselint/AnimalLabels.yml b/.github/.vale/proselint/AnimalLabels.yml new file mode 100644 index 00000000..b92e06fc --- /dev/null +++ b/.github/.vale/proselint/AnimalLabels.yml @@ -0,0 +1,48 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +level: error +action: + name: replace +swap: + (?:bull|ox)-like: taurine + (?:calf|veal)-like: vituline + (?:crow|raven)-like: corvine + (?:leopard|panther)-like: pardine + bird-like: avine + centipede-like: scolopendrine + crab-like: cancrine + crocodile-like: crocodiline + deer-like: damine + eagle-like: aquiline + earthworm-like: lumbricine + falcon-like: falconine + ferine: wild animal-like + fish-like: piscine + fox-like: vulpine + frog-like: ranine + goat-like: hircine + goose-like: anserine + gull-like: laridine + hare-like: leporine + hawk-like: accipitrine + hippopotamus-like: hippopotamine + lizard-like: lacertine + mongoose-like: viverrine + mouse-like: murine + ostrich-like: struthionine + peacock-like: pavonine + porcupine-like: hystricine + rattlesnake-like: crotaline + sable-like: zibeline + sheep-like: ovine + shrew-like: soricine + sparrow-like: passerine + swallow-like: hirundine + swine-like: suilline + tiger-like: tigrine + viper-like: viperine + vulture-like: vulturine + wasp-like: vespine + wolf-like: lupine + woodpecker-like: picine + zebra-like: zebrine diff --git a/.github/.vale/proselint/Annotations.yml b/.github/.vale/proselint/Annotations.yml new file mode 100644 index 00000000..83d9435c --- /dev/null +++ b/.github/.vale/proselint/Annotations.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' left in text." +ignorecase: false +level: error +tokens: + - XXX + - FIXME + - NOTE diff --git a/.github/.vale/proselint/Apologizing.yml b/.github/.vale/proselint/Apologizing.yml new file mode 100644 index 00000000..11088aaa --- /dev/null +++ b/.github/.vale/proselint/Apologizing.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Excessive apologizing: '%s'" +ignorecase: true +level: error +action: + name: remove +tokens: + - More research is needed diff --git a/.github/.vale/proselint/Archaisms.yml b/.github/.vale/proselint/Archaisms.yml new file mode 100644 index 00000000..c8df9abc --- /dev/null +++ b/.github/.vale/proselint/Archaisms.yml @@ -0,0 +1,52 @@ +extends: existence +message: "'%s' is archaic." +ignorecase: true +level: error +tokens: + - alack + - anent + - begat + - belike + - betimes + - boughten + - brocage + - brokage + - camarade + - chiefer + - chiefest + - Christiana + - completely obsolescent + - cozen + - divers + - deflexion + - fain + - forsooth + - foreclose from + - haply + - howbeit + - illumine + - in sooth + - maugre + - meseems + - methinks + - nigh + - peradventure + - perchance + - saith + - shew + - sistren + - spake + - to wit + - verily + - whilom + - withal + - wot + - enclosed please find + - please find enclosed + - enclosed herewith + - enclosed herein + - inforce + - ex postfacto + - foreclose from + - forewent + - for ever diff --git a/.github/.vale/proselint/But.yml b/.github/.vale/proselint/But.yml new file mode 100644 index 00000000..0e2c32b9 --- /dev/null +++ b/.github/.vale/proselint/But.yml @@ -0,0 +1,8 @@ +extends: existence +message: "Do not start a paragraph with a 'but'." +level: error +scope: paragraph +action: + name: remove +tokens: + - ^But diff --git a/.github/.vale/proselint/Cliches.yml b/.github/.vale/proselint/Cliches.yml new file mode 100644 index 00000000..c56183c5 --- /dev/null +++ b/.github/.vale/proselint/Cliches.yml @@ -0,0 +1,782 @@ +extends: existence +message: "'%s' is a cliche." +level: error +ignorecase: true +tokens: + - a chip off the old block + - a clean slate + - a dark and stormy night + - a far cry + - a fate worse than death + - a fine kettle of fish + - a loose cannon + - a penny saved is a penny earned + - a tough row to hoe + - a word to the wise + - ace in the hole + - acid test + - add insult to injury + - against all odds + - air your dirty laundry + - alas and alack + - all fun and games + - all hell broke loose + - all in a day's work + - all talk, no action + - all thumbs + - all your eggs in one basket + - all's fair in love and war + - all's well that ends well + - almighty dollar + - American as apple pie + - an axe to grind + - another day, another dollar + - armed to the teeth + - as luck would have it + - as old as time + - as the crow flies + - at loose ends + - at my wits end + - at the end of the day + - avoid like the plague + - babe in the woods + - back against the wall + - back in the saddle + - back to square one + - back to the drawing board + - bad to the bone + - badge of honor + - bald faced liar + - bald-faced lie + - ballpark figure + - banging your head against a brick wall + - baptism by fire + - barking up the wrong tree + - bat out of hell + - be all and end all + - beat a dead horse + - beat around the bush + - been there, done that + - beggars can't be choosers + - behind the eight ball + - bend over backwards + - benefit of the doubt + - bent out of shape + - best thing since sliced bread + - bet your bottom dollar + - better half + - better late than never + - better mousetrap + - better safe than sorry + - between a rock and a hard place + - between a rock and a hard place + - between Scylla and Charybdis + - between the devil and the deep blue see + - betwixt and between + - beyond the pale + - bide your time + - big as life + - big cheese + - big fish in a small pond + - big man on campus + - bigger they are the harder they fall + - bird in the hand + - bird's eye view + - birds and the bees + - birds of a feather flock together + - bit the hand that feeds you + - bite the bullet + - bite the dust + - bitten off more than he can chew + - black as coal + - black as pitch + - black as the ace of spades + - blast from the past + - bleeding heart + - blessing in disguise + - blind ambition + - blind as a bat + - blind leading the blind + - blissful ignorance + - blood is thicker than water + - blood sweat and tears + - blow a fuse + - blow off steam + - blow your own horn + - blushing bride + - boils down to + - bolt from the blue + - bone to pick + - bored stiff + - bored to tears + - bottomless pit + - boys will be boys + - bright and early + - brings home the bacon + - broad across the beam + - broken record + - brought back to reality + - bulk large + - bull by the horns + - bull in a china shop + - burn the midnight oil + - burning question + - burning the candle at both ends + - burst your bubble + - bury the hatchet + - busy as a bee + - but that's another story + - by hook or by crook + - call a spade a spade + - called onto the carpet + - calm before the storm + - can of worms + - can't cut the mustard + - can't hold a candle to + - case of mistaken identity + - cast aspersions + - cat got your tongue + - cat's meow + - caught in the crossfire + - caught red-handed + - chase a red herring + - checkered past + - chomping at the bit + - cleanliness is next to godliness + - clear as a bell + - clear as mud + - close to the vest + - cock and bull story + - cold shoulder + - come hell or high water + - comparing apples and oranges + - compleat + - conspicuous by its absence + - cool as a cucumber + - cool, calm, and collected + - cost a king's ransom + - count your blessings + - crack of dawn + - crash course + - creature comforts + - cross that bridge when you come to it + - crushing blow + - cry like a baby + - cry me a river + - cry over spilt milk + - crystal clear + - crystal clear + - curiosity killed the cat + - cut and dried + - cut through the red tape + - cut to the chase + - cute as a bugs ear + - cute as a button + - cute as a puppy + - cuts to the quick + - cutting edge + - dark before the dawn + - day in, day out + - dead as a doornail + - decision-making process + - devil is in the details + - dime a dozen + - divide and conquer + - dog and pony show + - dog days + - dog eat dog + - dog tired + - don't burn your bridges + - don't count your chickens + - don't look a gift horse in the mouth + - don't rock the boat + - don't step on anyone's toes + - don't take any wooden nickels + - down and out + - down at the heels + - down in the dumps + - down the hatch + - down to earth + - draw the line + - dressed to kill + - dressed to the nines + - drives me up the wall + - dubious distinction + - dull as dishwater + - duly authorized + - dyed in the wool + - eagle eye + - ear to the ground + - early bird catches the worm + - easier said than done + - easy as pie + - eat your heart out + - eat your words + - eleventh hour + - even the playing field + - every dog has its day + - every fiber of my being + - everything but the kitchen sink + - eye for an eye + - eyes peeled + - face the music + - facts of life + - fair weather friend + - fall by the wayside + - fan the flames + - far be it from me + - fast and loose + - feast or famine + - feather your nest + - feathered friends + - few and far between + - fifteen minutes of fame + - fills the bill + - filthy vermin + - fine kettle of fish + - first and foremost + - fish out of water + - fishing for a compliment + - fit as a fiddle + - fit the bill + - fit to be tied + - flash in the pan + - flat as a pancake + - flip your lid + - flog a dead horse + - fly by night + - fly the coop + - follow your heart + - for all intents and purposes + - for free + - for the birds + - for what it's worth + - force of nature + - force to be reckoned with + - forgive and forget + - fox in the henhouse + - free and easy + - free as a bird + - fresh as a daisy + - full steam ahead + - fun in the sun + - garbage in, garbage out + - gentle as a lamb + - get a kick out of + - get a leg up + - get down and dirty + - get the lead out + - get to the bottom of + - get with the program + - get your feet wet + - gets my goat + - gilding the lily + - gilding the lily + - give and take + - go against the grain + - go at it tooth and nail + - go for broke + - go him one better + - go the extra mile + - go with the flow + - goes without saying + - good as gold + - good deed for the day + - good things come to those who wait + - good time was had by all + - good times were had by all + - greased lightning + - greek to me + - green thumb + - green-eyed monster + - grist for the mill + - growing like a weed + - hair of the dog + - hand to mouth + - happy as a clam + - happy as a lark + - hasn't a clue + - have a nice day + - have a short fuse + - have high hopes + - have the last laugh + - haven't got a row to hoe + - he's got his hands full + - head honcho + - head over heels + - hear a pin drop + - heard it through the grapevine + - heart's content + - heavy as lead + - hem and haw + - high and dry + - high and mighty + - high as a kite + - his own worst enemy + - his work cut out for him + - hit paydirt + - hither and yon + - Hobson's choice + - hold your head up high + - hold your horses + - hold your own + - hold your tongue + - honest as the day is long + - horns of a dilemma + - horns of a dilemma + - horse of a different color + - hot under the collar + - hour of need + - I beg to differ + - icing on the cake + - if the shoe fits + - if the shoe were on the other foot + - if you catch my drift + - in a jam + - in a jiffy + - in a nutshell + - in a pig's eye + - in a pinch + - in a word + - in hot water + - in light of + - in the final analysis + - in the gutter + - in the last analysis + - in the nick of time + - in the thick of it + - in your dreams + - innocent bystander + - it ain't over till the fat lady sings + - it goes without saying + - it takes all kinds + - it takes one to know one + - it's a small world + - it's not what you know, it's who you know + - it's only a matter of time + - ivory tower + - Jack of all trades + - jockey for position + - jog your memory + - joined at the hip + - judge a book by its cover + - jump down your throat + - jump in with both feet + - jump on the bandwagon + - jump the gun + - jump to conclusions + - just a hop, skip, and a jump + - just the ticket + - justice is blind + - keep a stiff upper lip + - keep an eye on + - keep it simple, stupid + - keep the home fires burning + - keep up with the Joneses + - keep your chin up + - keep your fingers crossed + - kick the bucket + - kick up your heels + - kick your feet up + - kid in a candy store + - kill two birds with one stone + - kiss of death + - knock it out of the park + - knock on wood + - knock your socks off + - know him from Adam + - know the ropes + - know the score + - knuckle down + - knuckle sandwich + - knuckle under + - labor of love + - ladder of success + - land on your feet + - lap of luxury + - last but not least + - last but not least + - last hurrah + - last-ditch effort + - law of the jungle + - law of the land + - lay down the law + - leaps and bounds + - let sleeping dogs lie + - let the cat out of the bag + - let the good times roll + - let your hair down + - let's talk turkey + - letter perfect + - lick your wounds + - lies like a rug + - life's a bitch + - life's a grind + - light at the end of the tunnel + - lighter than a feather + - lighter than air + - like clockwork + - like father like son + - like taking candy from a baby + - like there's no tomorrow + - lion's share + - live and learn + - live and let live + - long and short of it + - long lost love + - look before you leap + - look down your nose + - look what the cat dragged in + - looking a gift horse in the mouth + - looks like death warmed over + - loose cannon + - lose your head + - lose your temper + - loud as a horn + - lounge lizard + - loved and lost + - low man on the totem pole + - luck of the draw + - luck of the Irish + - make a mockery of + - make hay while the sun shines + - make money hand over fist + - make my day + - make the best of a bad situation + - make the best of it + - make your blood boil + - male chauvinism + - man of few words + - man's best friend + - mark my words + - meaningful dialogue + - missed the boat on that one + - moment in the sun + - moment of glory + - moment of truth + - moment of truth + - money to burn + - more in sorrow than in anger + - more power to you + - more sinned against than sinning + - more than one way to skin a cat + - movers and shakers + - moving experience + - my better half + - naked as a jaybird + - naked truth + - neat as a pin + - needle in a haystack + - needless to say + - neither here nor there + - never look back + - never say never + - nip and tuck + - nip in the bud + - nip it in the bud + - no guts, no glory + - no love lost + - no pain, no gain + - no skin off my back + - no stone unturned + - no time like the present + - no use crying over spilled milk + - nose to the grindstone + - not a hope in hell + - not a minute's peace + - not in my backyard + - not playing with a full deck + - not the end of the world + - not written in stone + - nothing to sneeze at + - nothing ventured nothing gained + - now we're cooking + - off the top of my head + - off the wagon + - off the wall + - old hat + - olden days + - older and wiser + - older than dirt + - older than Methuselah + - on a roll + - on cloud nine + - on pins and needles + - on the bandwagon + - on the money + - on the nose + - on the rocks + - on the same page + - on the spot + - on the tip of my tongue + - on the wagon + - on thin ice + - once bitten, twice shy + - one bad apple doesn't spoil the bushel + - one born every minute + - one brick short + - one foot in the grave + - one in a million + - one red cent + - only game in town + - open a can of worms + - open and shut case + - open the flood gates + - opportunity doesn't knock twice + - out of pocket + - out of sight, out of mind + - out of the frying pan into the fire + - out of the woods + - out on a limb + - over a barrel + - over the hump + - pain and suffering + - pain in the + - panic button + - par for the course + - part and parcel + - party pooper + - pass the buck + - patience is a virtue + - pay through the nose + - penny pincher + - perfect storm + - pig in a poke + - pile it on + - pillar of the community + - pin your hopes on + - pitter patter of little feet + - plain as day + - plain as the nose on your face + - play by the rules + - play your cards right + - playing the field + - playing with fire + - pleased as punch + - plenty of fish in the sea + - point with pride + - poor as a church mouse + - pot calling the kettle black + - presidential timber + - pretty as a picture + - pull a fast one + - pull your punches + - pulled no punches + - pulling your leg + - pure as the driven snow + - put it in a nutshell + - put one over on you + - put the cart before the horse + - put the pedal to the metal + - put your best foot forward + - put your foot down + - quantum jump + - quantum leap + - quick as a bunny + - quick as a lick + - quick as a wink + - quick as lightning + - quiet as a dormouse + - rags to riches + - raining buckets + - raining cats and dogs + - rank and file + - rat race + - reap what you sow + - red as a beet + - red herring + - redound to one's credit + - redound to the benefit of + - reinvent the wheel + - rich and famous + - rings a bell + - ripe old age + - ripped me off + - rise and shine + - road to hell is paved with good intentions + - rob Peter to pay Paul + - roll over in the grave + - rub the wrong way + - ruled the roost + - running in circles + - sad but true + - sadder but wiser + - salt of the earth + - scared stiff + - scared to death + - sea change + - sealed with a kiss + - second to none + - see eye to eye + - seen the light + - seize the day + - set the record straight + - set the world on fire + - set your teeth on edge + - sharp as a tack + - shirked his duties + - shoot for the moon + - shoot the breeze + - shot in the dark + - shoulder to the wheel + - sick as a dog + - sigh of relief + - signed, sealed, and delivered + - sink or swim + - six of one, half a dozen of another + - six of one, half a dozen of the other + - skating on thin ice + - slept like a log + - slinging mud + - slippery as an eel + - slow as molasses + - smart as a whip + - smooth as a baby's bottom + - sneaking suspicion + - snug as a bug in a rug + - sow wild oats + - spare the rod, spoil the child + - speak of the devil + - spilled the beans + - spinning your wheels + - spitting image of + - spoke with relish + - spread like wildfire + - spring to life + - squeaky wheel gets the grease + - stands out like a sore thumb + - start from scratch + - stick in the mud + - still waters run deep + - stitch in time + - stop and smell the roses + - straight as an arrow + - straw that broke the camel's back + - stretched to the breaking point + - strong as an ox + - stubborn as a mule + - stuff that dreams are made of + - stuffed shirt + - sweating blood + - sweating bullets + - take a load off + - take one for the team + - take the bait + - take the bull by the horns + - take the plunge + - takes one to know one + - takes two to tango + - than you can shake a stick at + - the cream of the crop + - the cream rises to the top + - the more the merrier + - the real deal + - the real McCoy + - the red carpet treatment + - the same old story + - the straw that broke the camel's back + - there is no accounting for taste + - thick as a brick + - thick as thieves + - thick as thieves + - thin as a rail + - think outside of the box + - thinking outside the box + - third time's the charm + - this day and age + - this hurts me worse than it hurts you + - this point in time + - thought leaders? + - three sheets to the wind + - through thick and thin + - throw in the towel + - throw the baby out with the bathwater + - tie one on + - tighter than a drum + - time and time again + - time is of the essence + - tip of the iceberg + - tired but happy + - to coin a phrase + - to each his own + - to make a long story short + - to the best of my knowledge + - toe the line + - tongue in cheek + - too good to be true + - too hot to handle + - too numerous to mention + - touch with a ten foot pole + - tough as nails + - trial and error + - trials and tribulations + - tried and true + - trip down memory lane + - twist of fate + - two cents worth + - two peas in a pod + - ugly as sin + - under the counter + - under the gun + - under the same roof + - under the weather + - until the cows come home + - unvarnished truth + - up the creek + - uphill battle + - upper crust + - upset the applecart + - vain attempt + - vain effort + - vanquish the enemy + - various and sundry + - vested interest + - viable alternative + - waiting for the other shoe to drop + - wakeup call + - warm welcome + - watch your p's and q's + - watch your tongue + - watching the clock + - water under the bridge + - wax eloquent + - wax poetic + - we've got a situation here + - weather the storm + - weed them out + - week of Sundays + - went belly up + - wet behind the ears + - what goes around comes around + - what you see is what you get + - when it rains, it pours + - when push comes to shove + - when the cat's away + - when the going gets tough, the tough get going + - whet (?:the|your) appetite + - white as a sheet + - whole ball of wax + - whole hog + - whole nine yards + - wild goose chase + - will wonders never cease? + - wisdom of the ages + - wise as an owl + - wolf at the door + - wool pulled over our eyes + - words fail me + - work like a dog + - world weary + - worst nightmare + - worth its weight in gold + - writ large + - wrong side of the bed + - yanking your chain + - yappy as a dog + - years young + - you are what you eat + - you can run but you can't hide + - you only live once + - you're the boss + - young and foolish + - young and vibrant diff --git a/.github/.vale/proselint/CorporateSpeak.yml b/.github/.vale/proselint/CorporateSpeak.yml new file mode 100644 index 00000000..4de8ee3f --- /dev/null +++ b/.github/.vale/proselint/CorporateSpeak.yml @@ -0,0 +1,30 @@ +extends: existence +message: "'%s' is corporate speak." +ignorecase: true +level: error +tokens: + - at the end of the day + - back to the drawing board + - hit the ground running + - get the ball rolling + - low-hanging fruit + - thrown under the bus + - think outside the box + - let's touch base + - get my manager's blessing + - it's on my radar + - ping me + - i don't have the bandwidth + - no brainer + - par for the course + - bang for your buck + - synergy + - move the goal post + - apples to apples + - win-win + - circle back around + - all hands on deck + - take this offline + - drill-down + - elephant in the room + - on my plate diff --git a/.github/.vale/proselint/Currency.yml b/.github/.vale/proselint/Currency.yml new file mode 100644 index 00000000..ebd4b7d3 --- /dev/null +++ b/.github/.vale/proselint/Currency.yml @@ -0,0 +1,5 @@ +extends: existence +message: "Incorrect use of symbols in '%s'." +ignorecase: true +raw: + - \$[\d]* ?(?:dollars|usd|us dollars) diff --git a/.github/.vale/proselint/Cursing.yml b/.github/.vale/proselint/Cursing.yml new file mode 100644 index 00000000..e65070a9 --- /dev/null +++ b/.github/.vale/proselint/Cursing.yml @@ -0,0 +1,15 @@ +extends: existence +message: "Consider replacing '%s'." +level: error +ignorecase: true +tokens: + - shit + - piss + - fuck + - cunt + - cocksucker + - motherfucker + - tits + - fart + - turd + - twat diff --git a/.github/.vale/proselint/DateCase.yml b/.github/.vale/proselint/DateCase.yml new file mode 100644 index 00000000..9aa1bd99 --- /dev/null +++ b/.github/.vale/proselint/DateCase.yml @@ -0,0 +1,7 @@ +extends: existence +message: With lowercase letters, the periods are standard. +ignorecase: false +level: error +nonword: true +tokens: + - '\d{1,2} ?[ap]m\b' diff --git a/.github/.vale/proselint/DateMidnight.yml b/.github/.vale/proselint/DateMidnight.yml new file mode 100644 index 00000000..0130e1ae --- /dev/null +++ b/.github/.vale/proselint/DateMidnight.yml @@ -0,0 +1,7 @@ +extends: existence +message: "Use 'midnight' or 'noon'." +ignorecase: true +level: error +nonword: true +tokens: + - '12 ?[ap]\.?m\.?' diff --git a/.github/.vale/proselint/DateRedundancy.yml b/.github/.vale/proselint/DateRedundancy.yml new file mode 100644 index 00000000..b1f653ea --- /dev/null +++ b/.github/.vale/proselint/DateRedundancy.yml @@ -0,0 +1,10 @@ +extends: existence +message: "'a.m.' is always morning; 'p.m.' is always night." +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2} ?a\.?m\.? in the morning' + - '\d{1,2} ?p\.?m\.? in the evening' + - '\d{1,2} ?p\.?m\.? at night' + - '\d{1,2} ?p\.?m\.? in the afternoon' diff --git a/.github/.vale/proselint/DateSpacing.yml b/.github/.vale/proselint/DateSpacing.yml new file mode 100644 index 00000000..b7a2fd33 --- /dev/null +++ b/.github/.vale/proselint/DateSpacing.yml @@ -0,0 +1,7 @@ +extends: existence +message: "It's standard to put a space before '%s'" +ignorecase: true +level: error +nonword: true +tokens: + - '\d{1,2}[ap]\.?m\.?' diff --git a/.github/.vale/proselint/DenizenLabels.yml b/.github/.vale/proselint/DenizenLabels.yml new file mode 100644 index 00000000..bc3dd8ab --- /dev/null +++ b/.github/.vale/proselint/DenizenLabels.yml @@ -0,0 +1,52 @@ +extends: substitution +message: Did you mean '%s'? +ignorecase: false +action: + name: replace +swap: + (?:Afrikaaner|Afrikander): Afrikaner + (?:Hong Kongite|Hong Kongian): Hong Konger + (?:Indianan|Indianian): Hoosier + (?:Michiganite|Michiganian): Michigander + (?:New Hampshireite|New Hampshireman): New Hampshirite + (?:Newcastlite|Newcastleite): Novocastrian + (?:Providencian|Providencer): Providentian + (?:Trentian|Trentonian): Tridentine + (?:Warsawer|Warsawian): Varsovian + (?:Wolverhamptonite|Wolverhamptonian): Wulfrunian + Alabaman: Alabamian + Albuquerquian: Albuquerquean + Anchoragite: Anchorageite + Arizonian: Arizonan + Arkansawyer: Arkansan + Belarusan: Belarusian + Cayman Islander: Caymanian + Coloradoan: Coloradan + Connecticuter: Nutmegger + Fairbanksian: Fairbanksan + Fort Worther: Fort Worthian + Grenadian: Grenadan + Halifaxer: Haligonian + Hartlepoolian: Hartlepudlian + Illinoisian: Illinoisan + Iowegian: Iowan + Leedsian: Leodenisian + Liverpoolian: Liverpudlian + Los Angelean: Angeleno + Manchesterian: Mancunian + Minneapolisian: Minneapolitan + Missouran: Missourian + Monacan: Monegasque + Neopolitan: Neapolitan + New Jerseyite: New Jerseyan + New Orleansian: New Orleanian + Oklahoma Citian: Oklahoma Cityan + Oklahomian: Oklahoman + Saudi Arabian: Saudi + Seattlite: Seattleite + Surinamer: Surinamese + Tallahassean: Tallahasseean + Tennesseean: Tennessean + Trois-Rivièrester: Trifluvian + Utahan: Utahn + Valladolidian: Vallisoletano diff --git a/.github/.vale/proselint/Diacritical.yml b/.github/.vale/proselint/Diacritical.yml new file mode 100644 index 00000000..2416cf28 --- /dev/null +++ b/.github/.vale/proselint/Diacritical.yml @@ -0,0 +1,95 @@ +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +level: error +action: + name: replace +swap: + beau ideal: beau idéal + boutonniere: boutonnière + bric-a-brac: bric-à-brac + cafe: café + cause celebre: cause célèbre + chevre: chèvre + cliche: cliché + consomme: consommé + coup de grace: coup de grâce + crudites: crudités + creme brulee: crème brûlée + creme de menthe: crème de menthe + creme fraice: crème fraîche + creme fresh: crème fraîche + crepe: crêpe + debutante: débutante + decor: décor + deja vu: déjà vu + denouement: dénouement + facade: façade + fiance: fiancé + fiancee: fiancée + flambe: flambé + garcon: garçon + lycee: lycée + maitre d: maître d + menage a trois: ménage à trois + negligee: négligée + protege: protégé + protegee: protégée + puree: purée + my resume: my résumé + your resume: your résumé + his resume: his résumé + her resume: her résumé + a resume: a résumé + the resume: the résumé + risque: risqué + roue: roué + soiree: soirée + souffle: soufflé + soupcon: soupçon + touche: touché + tete-a-tete: tête-à-tête + voila: voilà + a la carte: à la carte + a la mode: à la mode + emigre: émigré + + # Spanish loanwords + El Nino: El Niño + jalapeno: jalapeño + La Nina: La Niña + pina colada: piña colada + senor: señor + senora: señora + senorita: señorita + + # Portuguese loanwords + acai: açaí + + # German loanwords + doppelganger: doppelgänger + Fuhrer: Führer + Gewurztraminer: Gewürztraminer + vis-a-vis: vis-à-vis + Ubermensch: Übermensch + + # Swedish loanwords + filmjolk: filmjölk + smorgasbord: smörgåsbord + + # Names, places, and companies + Beyonce: Beyoncé + Bronte: Brontë + Champs-Elysees: Champs-Élysées + Citroen: Citroën + Curacao: Curaçao + Lowenbrau: Löwenbräu + Monegasque: Monégasque + Motley Crue: Mötley Crüe + Nescafe: Nescafé + Queensryche: Queensrÿche + Quebec: Québec + Quebecois: Québécois + Angstrom: Ångström + angstrom: ångström + Skoda: Škoda diff --git a/.github/.vale/proselint/GenderBias.yml b/.github/.vale/proselint/GenderBias.yml new file mode 100644 index 00000000..833a6791 --- /dev/null +++ b/.github/.vale/proselint/GenderBias.yml @@ -0,0 +1,44 @@ +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +level: error +action: + name: replace +swap: + (?:alumnae|alumni): graduates + (?:alumna|alumnus): graduate + air(?:m[ae]n|wom[ae]n): pilot(s) + anchor(?:m[ae]n|wom[ae]n): anchor(s) + authoress: author + camera(?:m[ae]n|wom[ae]n): camera operator(s) + chair(?:m[ae]n|wom[ae]n): chair(s) + congress(?:m[ae]n|wom[ae]n): member(s) of congress + door(?:m[ae]|wom[ae]n): concierge(s) + draft(?:m[ae]n|wom[ae]n): drafter(s) + fire(?:m[ae]n|wom[ae]n): firefighter(s) + fisher(?:m[ae]n|wom[ae]n): fisher(s) + fresh(?:m[ae]n|wom[ae]n): first-year student(s) + garbage(?:m[ae]n|wom[ae]n): waste collector(s) + lady lawyer: lawyer + ladylike: courteous + landlord: building manager + mail(?:m[ae]n|wom[ae]n): mail carriers + man and wife: husband and wife + man enough: strong enough + mankind: human kind + manmade: manufactured + men and girls: men and women + middle(?:m[ae]n|wom[ae]n): intermediary + news(?:m[ae]n|wom[ae]n): journalist(s) + ombuds(?:man|woman): ombuds + oneupmanship: upstaging + poetess: poet + police(?:m[ae]n|wom[ae]n): police officer(s) + repair(?:m[ae]n|wom[ae]n): technician(s) + sales(?:m[ae]n|wom[ae]n): salesperson or sales people + service(?:m[ae]n|wom[ae]n): soldier(s) + tribes(?:m[ae]n|wom[ae]n): tribe member(s) + waitress: waiter + woman doctor: doctor + woman scientist[s]?: scientist(s) + work(?:m[ae]n|wom[ae]n): worker(s) diff --git a/.github/.vale/proselint/GroupTerms.yml b/.github/.vale/proselint/GroupTerms.yml new file mode 100644 index 00000000..7a59fa48 --- /dev/null +++ b/.github/.vale/proselint/GroupTerms.yml @@ -0,0 +1,39 @@ +extends: substitution +message: Consider using '%s' instead of '%s'. +ignorecase: true +action: + name: replace +swap: + (?:bunch|group|pack|flock) of chickens: brood of chickens + (?:bunch|group|pack|flock) of crows: murder of crows + (?:bunch|group|pack|flock) of hawks: cast of hawks + (?:bunch|group|pack|flock) of parrots: pandemonium of parrots + (?:bunch|group|pack|flock) of peacocks: muster of peacocks + (?:bunch|group|pack|flock) of penguins: muster of penguins + (?:bunch|group|pack|flock) of sparrows: host of sparrows + (?:bunch|group|pack|flock) of turkeys: rafter of turkeys + (?:bunch|group|pack|flock) of woodpeckers: descent of woodpeckers + (?:bunch|group|pack|herd) of apes: shrewdness of apes + (?:bunch|group|pack|herd) of baboons: troop of baboons + (?:bunch|group|pack|herd) of badgers: cete of badgers + (?:bunch|group|pack|herd) of bears: sloth of bears + (?:bunch|group|pack|herd) of bullfinches: bellowing of bullfinches + (?:bunch|group|pack|herd) of bullocks: drove of bullocks + (?:bunch|group|pack|herd) of caterpillars: army of caterpillars + (?:bunch|group|pack|herd) of cats: clowder of cats + (?:bunch|group|pack|herd) of colts: rag of colts + (?:bunch|group|pack|herd) of crocodiles: bask of crocodiles + (?:bunch|group|pack|herd) of dolphins: school of dolphins + (?:bunch|group|pack|herd) of foxes: skulk of foxes + (?:bunch|group|pack|herd) of gorillas: band of gorillas + (?:bunch|group|pack|herd) of hippopotami: bloat of hippopotami + (?:bunch|group|pack|herd) of horses: drove of horses + (?:bunch|group|pack|herd) of jellyfish: fluther of jellyfish + (?:bunch|group|pack|herd) of kangeroos: mob of kangeroos + (?:bunch|group|pack|herd) of monkeys: troop of monkeys + (?:bunch|group|pack|herd) of oxen: yoke of oxen + (?:bunch|group|pack|herd) of rhinoceros: crash of rhinoceros + (?:bunch|group|pack|herd) of wild boar: sounder of wild boar + (?:bunch|group|pack|herd) of wild pigs: drift of wild pigs + (?:bunch|group|pack|herd) of zebras: zeal of wild pigs + (?:bunch|group|pack|school) of trout: hover of trout diff --git a/.github/.vale/proselint/Hedging.yml b/.github/.vale/proselint/Hedging.yml new file mode 100644 index 00000000..a8615f8b --- /dev/null +++ b/.github/.vale/proselint/Hedging.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' is hedging." +ignorecase: true +level: error +tokens: + - I would argue that + - ', so to speak' + - to a certain degree diff --git a/.github/.vale/proselint/Hyperbole.yml b/.github/.vale/proselint/Hyperbole.yml new file mode 100644 index 00000000..0361772c --- /dev/null +++ b/.github/.vale/proselint/Hyperbole.yml @@ -0,0 +1,6 @@ +extends: existence +message: "'%s' is hyperbolic." +level: error +nonword: true +tokens: + - '[a-z]+[!?]{2,}' diff --git a/.github/.vale/proselint/Jargon.yml b/.github/.vale/proselint/Jargon.yml new file mode 100644 index 00000000..2454a9c3 --- /dev/null +++ b/.github/.vale/proselint/Jargon.yml @@ -0,0 +1,11 @@ +extends: existence +message: "'%s' is jargon." +ignorecase: true +level: error +tokens: + - in the affirmative + - in the negative + - agendize + - per your order + - per your request + - disincentivize diff --git a/.github/.vale/proselint/LGBTOffensive.yml b/.github/.vale/proselint/LGBTOffensive.yml new file mode 100644 index 00000000..eaf5a84a --- /dev/null +++ b/.github/.vale/proselint/LGBTOffensive.yml @@ -0,0 +1,13 @@ +extends: existence +message: "'%s' is offensive. Remove it or consider the context." +ignorecase: true +tokens: + - fag + - faggot + - dyke + - sodomite + - homosexual agenda + - gay agenda + - transvestite + - homosexual lifestyle + - gay lifestyle diff --git a/.github/.vale/proselint/LGBTTerms.yml b/.github/.vale/proselint/LGBTTerms.yml new file mode 100644 index 00000000..efdf2688 --- /dev/null +++ b/.github/.vale/proselint/LGBTTerms.yml @@ -0,0 +1,15 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +action: + name: replace +swap: + homosexual man: gay man + homosexual men: gay men + homosexual woman: lesbian + homosexual women: lesbians + homosexual people: gay people + homosexual couple: gay couple + sexual preference: sexual orientation + (?:admitted homosexual|avowed homosexual): openly gay + special rights: equal rights diff --git a/.github/.vale/proselint/Malapropisms.yml b/.github/.vale/proselint/Malapropisms.yml new file mode 100644 index 00000000..96997787 --- /dev/null +++ b/.github/.vale/proselint/Malapropisms.yml @@ -0,0 +1,8 @@ +extends: existence +message: "'%s' is a malapropism." +ignorecase: true +level: error +tokens: + - the infinitesimal universe + - a serial experience + - attack my voracity diff --git a/.github/.vale/proselint/Needless.yml b/.github/.vale/proselint/Needless.yml new file mode 100644 index 00000000..1f2732e1 --- /dev/null +++ b/.github/.vale/proselint/Needless.yml @@ -0,0 +1,358 @@ +extends: substitution +message: Prefer '%s' over '%s' +ignorecase: true +action: + name: replace +swap: + '(?:cell phone|cell-phone)': cellphone + '(?:cliquey|cliquy)': cliquish + '(?:pygmean|pygmaen)': pygmy + '(?:retributional|retributionary)': retributive + '(?:revokable|revokeable)': revocable + abolishment: abolition + accessary: accessory + accreditate: accredit + accruement: accrual + accusee: accused + acquaintanceship: acquaintance + acquitment: acquittal + administrate: administer + administrated: administered + administrating: administering + adulterate: adulterous + advisatory: advisory + advocator: advocate + aggrievance: grievance + allegator: alleger + allusory: allusive + amative: amorous + amortizement: amortization + amphiboly: amphibology + anecdotalist: anecdotist + anilinctus: anilingus + anticipative: anticipatory + antithetic: antithetical + applicative: applicable + applicatory: applicable + applier: applicator + approbative: approbatory + arbitrager: arbitrageur + arsenous: arsenious + ascendance: ascendancy + ascendence: ascendancy + ascendency: ascendancy + auctorial: authorial + averral: averment + barbwire: barbed wire + benefic: beneficent + benignant: benign + bestowment: bestowal + betrothment: betrothal + blamableness: blameworthiness + butt naked: buck naked + camarade: comrade + carta blanca: carte blanche + casualities: casualties + casuality: casualty + catch on fire: catch fire + catholicly: catholically + cease fire: ceasefire + channelize: channel + chaplainship: chaplaincy + chrysalid: chrysalis + chrysalids: chrysalises + cigaret: cigarette + coemployee: coworker + cognitional: cognitive + cohabitate: cohabit + cohabitor: cohabitant + collodium: collodion + collusory: collusive + commemoratory: commemorative + commonty: commonage + communicatory: communicative + compensative: compensatory + complacence: complacency + complicitous: complicit + computate: compute + conciliative: conciliatory + concomitancy: concomitance + condonance: condonation + confirmative: confirmatory + congruency: congruence + connotate: connote + consanguineal: consanguine + conspicuity: conspicuousness + conspiratorialist: conspirator + constitutionist: constitutionalist + contingence: contigency + contributary: contributory + contumacity: contumacy + conversible: convertible + conveyal: conveyance + copartner: partner + copartnership: partnership + corroboratory: corroborative + cotemporaneous: contemporaneous + cotemporary: contemporary + criminate: incriminate + culpatory: inculpatory + cumbrance: encumbrance + cumulate: accumulate + curatory: curative + daredeviltry: daredevilry + deceptious: deceptive + defamative: defamatory + defraudulent: fraudulent + degeneratory: degenerative + delimitate: delimit + delusory: delusive + denouncement: denunciation + depositee: depositary + depreciative: depreciatory + deprival: deprivation + derogative: derogatory + destroyable: destructible + detoxicate: detoxify + detractory: detractive + deviancy: deviance + deviationist: deviant + digamy: deuterogamy + digitalize: digitize + diminishment: diminution + diplomatist: diplomat + disassociate: dissociate + disciplinatory: disciplinary + discriminant: discriminating + disenthrone: dethrone + disintegratory: disintegrative + dismission: dismissal + disorientate: disorient + disorientated: disoriented + disquieten: disquiet + distraite: distrait + divergency: divergence + dividable: divisible + doctrinary: doctrinaire + documental: documentary + domesticize: domesticate + duplicatory: duplicative + duteous: dutiful + educationalist: educationist + educatory: educative + enigmatas: enigmas + enlargen: enlarge + enswathe: swathe + epical: epic + erotism: eroticism + ethician: ethicist + ex officiis: ex officio + exculpative: exculpatory + exigeant: exigent + exigence: exigency + exotism: exoticism + expedience: expediency + expediential: expedient + extensible: extendable + eying: eyeing + fiefdom: fief + flagrance: flagrancy + flatulency: flatulence + fraudful: fraudulent + funebrial: funereal + geographical: geographic + geometrical: geometric + gerry-rigged: jury-rigged + goatherder: goatherd + gustatorial: gustatory + habitude: habit + henceforward: henceforth + hesitance: hesitancy + heterogenous: heterogeneous + hierarchic: hierarchical + hindermost: hindmost + honorand: honoree + hypostasize: hypostatize + hysteric: hysterical + idolatrize: idolize + impanel: empanel + imperviable: impervious + importunacy: importunity + impotency: impotence + imprimatura: imprimatur + improprietous: improper + inalterable: unalterable + incitation: incitement + incommunicative: uncommunicative + inconsistence: inconsistency + incontrollable: uncontrollable + incurment: incurrence + indow: endow + indue: endue + inhibitive: inhibitory + innavigable: unnavigable + innovational: innovative + inquisitional: inquisitorial + insistment: insistence + insolvable: unsolvable + instillment: instillation + instinctual: instinctive + insuror: insurer + insurrectional: insurrectionary + interpretate: interpret + intervenience: intervention + ironical: ironic + jerry-rigged: jury-rigged + judgmatic: judgmental + labyrinthian: labyrinthine + laudative: laudatory + legitimatization: legitimation + legitimatize: legitimize + legitimization: legitimation + lengthways: lengthwise + life-sized: life-size + liquorice: licorice + lithesome: lithe + lollipop: lollypop + loth: loath + lubricous: lubricious + maihem: mayhem + medicinal marijuana: medical marijuana + meliorate: ameliorate + minimalize: minimize + mirk: murk + mirky: murky + misdoubt: doubt + monetarize: monetize + moveable: movable + narcism: narcissism + neglective: neglectful + negligency: negligence + neologizer: neologist + neurologic: neurological + nicknack: knickknack + nictate: nictitate + nonenforceable: unenforceable + normalcy: normality + numbedness: numbness + omittable: omissible + onomatopoetic: onomatopoeic + opinioned: opined + optimum advantage: optimal advantage + orientate: orient + outsized: outsize + oversized: oversize + overthrowal: overthrow + pacificist: pacifist + paederast: pederast + parachronism: anachronism + parti-color: parti-colored + participative: participatory + party-colored: parti-colored + pediatrist: pediatrician + penumbrous: penumbral + perjorative: pejorative + permissory: permissive + permutate: permute + personation: impersonation + pharmaceutic: pharmaceutical + pleuritis: pleurisy + policy holder: policyholder + policyowner: policyholder + politicalize: politicize + precedency: precedence + preceptoral: preceptorial + precipitance: precipitancy + precipitant: precipitate + preclusory: preclusive + precolumbian: pre-Columbian + prefectoral: prefectorial + preponderately: preponderantly + preserval: preservation + preventative: preventive + proconsulship: proconsulate + procreational: procreative + procurance: procurement + propelment: propulsion + propulsory: propulsive + prosecutive: prosecutory + protectory: protective + provocatory: provocative + pruriency: prurience + psychal: psychical + punitory: punitive + quantitate: quantify + questionary: questionnaire + quiescency: quiescence + rabbin: rabbi + reasonability: reasonableness + recidivistic: recidivous + recriminative: recriminatory + recruital: recruitment + recurrency: recurrence + recusance: recusancy + recusation: recusal + recusement: recusal + redemptory: redemptive + referrable: referable + referrible: referable + refutatory: refutative + remitment: remittance + remittal: remission + renouncement: renunciation + renunciable: renounceable + reparatory: reparative + repudiative: repudiatory + requitement: requital + rescindment: rescission + restoral: restoration + reticency: reticence + reviewal: review + revisal: revision + revisional: revisionary + revolute: revolt + saliency: salience + salutiferous: salutary + sensatory: sensory + sessionary: sessional + shareowner: shareholder + sicklily: sickly + signator: signatory + slanderize: slander + societary: societal + sodomist: sodomite + solicitate: solicit + speculatory: speculative + spiritous: spirituous + statutorial: statutory + submergeable: submersible + submittal: submission + subtile: subtle + succuba: succubus + sufficience: sufficiency + suppliant: supplicant + surmisal: surmise + suspendible: suspendable + synthetize: synthesize + systemize: systematize + tactual: tactile + tangental: tangential + tautologous: tautological + tee-shirt: T-shirt + thenceforward: thenceforth + transiency: transience + transposal: transposition + unfrequent: infrequent + unreasonability: unreasonableness + unrevokable: irrevocable + unsubstantial: insubstantial + usurpature: usurpation + variative: variational + vegetive: vegetative + vindicative: vindictive + vituperous: vituperative + vociferant: vociferous + volitive: volitional + wolverene: wolverine + wolvish: wolfish + Zoroastrism: Zoroastrianism diff --git a/.github/.vale/proselint/Nonwords.yml b/.github/.vale/proselint/Nonwords.yml new file mode 100644 index 00000000..57e7b9e4 --- /dev/null +++ b/.github/.vale/proselint/Nonwords.yml @@ -0,0 +1,38 @@ +extends: substitution +message: "Consider using '%s' instead of '%s'." +ignorecase: true +level: error +action: + name: replace +swap: + affrontery: effrontery + analyzation: analysis + annoyment: annoyance + confirmant: confirmand + confirmants: confirmands + conversate: converse + crained: cranded + discomforture: discomfort|discomfiture + dispersement: disbursement|dispersal + doubtlessly: doubtless|undoubtedly + forebearance: forbearance + improprietous: improper + inclimate: inclement + inimicable: inimical + irregardless: regardless + minimalize: minimize + minimalized: minimized + minimalizes: minimizes + minimalizing: minimizing + optimalize: optimize + paralyzation: paralysis + pettifogger: pettifog + proprietous: proper + relative inexpense: relatively low price|affordability + seldomly: seldom + thusly: thus + uncategorically: categorically + undoubtably: undoubtedly|indubitably + unequivocable: unequivocal + unmercilessly: mercilessly + unrelentlessly: unrelentingly|relentlessly diff --git a/.github/.vale/proselint/Oxymorons.yml b/.github/.vale/proselint/Oxymorons.yml new file mode 100644 index 00000000..25fd2aa5 --- /dev/null +++ b/.github/.vale/proselint/Oxymorons.yml @@ -0,0 +1,22 @@ +extends: existence +message: "'%s' is an oxymoron." +ignorecase: true +level: error +tokens: + - amateur expert + - increasingly less + - advancing backwards + - alludes explicitly to + - explicitly alludes to + - totally obsolescent + - completely obsolescent + - generally always + - usually always + - increasingly less + - build down + - conspicuous absence + - exact estimate + - found missing + - intense apathy + - mandatory choice + - organized mess diff --git a/.github/.vale/proselint/P-Value.yml b/.github/.vale/proselint/P-Value.yml new file mode 100644 index 00000000..82309386 --- /dev/null +++ b/.github/.vale/proselint/P-Value.yml @@ -0,0 +1,6 @@ +extends: existence +message: "You should use more decimal places, unless '%s' is really true." +ignorecase: true +level: suggestion +tokens: + - 'p = 0\.0{2,4}' diff --git a/.github/.vale/proselint/RASSyndrome.yml b/.github/.vale/proselint/RASSyndrome.yml new file mode 100644 index 00000000..deae9c7d --- /dev/null +++ b/.github/.vale/proselint/RASSyndrome.yml @@ -0,0 +1,30 @@ +extends: existence +message: "'%s' is redundant." +level: error +action: + name: edit + params: + - split + - ' ' + - '0' +tokens: + - ABM missile + - ACT test + - ABM missiles + - ABS braking system + - ATM machine + - CD disc + - CPI Index + - GPS system + - GUI interface + - HIV virus + - ISBN number + - LCD display + - PDF format + - PIN number + - RAS syndrome + - RIP in peace + - please RSVP + - SALT talks + - SAT test + - UPC codes diff --git a/.github/.vale/proselint/README.md b/.github/.vale/proselint/README.md new file mode 100644 index 00000000..40207686 --- /dev/null +++ b/.github/.vale/proselint/README.md @@ -0,0 +1,12 @@ +Copyright © 2014–2015, Jordan Suchow, Michael Pacer, and Lara A. Ross +All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/.github/.vale/proselint/Skunked.yml b/.github/.vale/proselint/Skunked.yml new file mode 100644 index 00000000..96a1f690 --- /dev/null +++ b/.github/.vale/proselint/Skunked.yml @@ -0,0 +1,13 @@ +extends: existence +message: "'%s' is a bit of a skunked term — impossible to use without issue." +ignorecase: true +level: error +tokens: + - bona fides + - deceptively + - decimate + - effete + - fulsome + - hopefully + - impassionate + - Thankfully diff --git a/.github/.vale/proselint/Spelling.yml b/.github/.vale/proselint/Spelling.yml new file mode 100644 index 00000000..d3c9be7b --- /dev/null +++ b/.github/.vale/proselint/Spelling.yml @@ -0,0 +1,17 @@ +extends: consistency +message: "Inconsistent spelling of '%s'." +level: error +ignorecase: true +either: + advisor: adviser + centre: center + colour: color + emphasise: emphasize + finalise: finalize + focussed: focused + labour: labor + learnt: learned + organise: organize + organised: organized + organising: organizing + recognise: recognize diff --git a/.github/.vale/proselint/Typography.yml b/.github/.vale/proselint/Typography.yml new file mode 100644 index 00000000..60283ebf --- /dev/null +++ b/.github/.vale/proselint/Typography.yml @@ -0,0 +1,11 @@ +extends: substitution +message: Consider using the '%s' symbol instead of '%s'. +level: error +nonword: true +swap: + '\.\.\.': … + '\([cC]\)': © + '\(TM\)': ™ + '\(tm\)': ™ + '\([rR]\)': ® + '[0-9]+ ?x ?[0-9]+': × diff --git a/.github/.vale/proselint/Uncomparables.yml b/.github/.vale/proselint/Uncomparables.yml new file mode 100644 index 00000000..9b96f42b --- /dev/null +++ b/.github/.vale/proselint/Uncomparables.yml @@ -0,0 +1,50 @@ +extends: existence +message: "'%s' is not comparable" +ignorecase: true +level: error +action: + name: edit + params: + - split + - ' ' + - '1' +raw: + - \b(?:absolutely|most|more|less|least|very|quite|largely|extremely|increasingly|kind of|mildy|hardly|greatly|sort of)\b\s* +tokens: + - absolute + - adequate + - complete + - correct + - certain + - devoid + - entire + - 'false' + - fatal + - favorite + - final + - ideal + - impossible + - inevitable + - infinite + - irrevocable + - main + - manifest + - only + - paramount + - perfect + - perpetual + - possible + - preferable + - principal + - singular + - stationary + - sufficient + - 'true' + - unanimous + - unavoidable + - unbroken + - uniform + - unique + - universal + - void + - whole diff --git a/.github/.vale/proselint/Very.yml b/.github/.vale/proselint/Very.yml new file mode 100644 index 00000000..e4077f79 --- /dev/null +++ b/.github/.vale/proselint/Very.yml @@ -0,0 +1,6 @@ +extends: existence +message: "Remove '%s'." +ignorecase: true +level: error +tokens: + - very diff --git a/.github/.vale/proselint/meta.json b/.github/.vale/proselint/meta.json new file mode 100644 index 00000000..e3c65800 --- /dev/null +++ b/.github/.vale/proselint/meta.json @@ -0,0 +1,17 @@ +{ + "author": "jdkato", + "description": "A Vale-compatible implementation of the proselint linter.", + "email": "support@errata.ai", + "lang": "en", + "url": "https://github.com/errata-ai/proselint/releases/latest/download/proselint.zip", + "feed": "https://github.com/errata-ai/proselint/releases.atom", + "issues": "https://github.com/errata-ai/proselint/issues/new", + "license": "BSD-3-Clause", + "name": "proselint", + "sources": [ + "https://github.com/amperser/proselint" + ], + "vale_version": ">=1.0.0", + "coverage": 0.0, + "version": "0.1.0" +} diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml new file mode 100644 index 00000000..ffded44e --- /dev/null +++ b/.github/workflows/proofreading-vale.yml @@ -0,0 +1,15 @@ +name: reviewdog +on: [pull_request] + +jobs: + vale: + name: runner / vale + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: errata-ai/vale-action@reviewdog + with: + files: content + with: + # github-pr-check, github-pr-review, github-check + reporter: github-pr-check \ No newline at end of file diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..16554a08 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,5 @@ +StylesPath = .github\.vale +MinAlertLevel = suggestion + +[*.md] +BasedOnStyles = Vale \ No newline at end of file From 0d4e58ae9601e652ce4516eb1b4d052f04c41ebd Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 12 Sep 2024 16:03:28 +0300 Subject: [PATCH 09/74] Fixing workflow file Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index ffded44e..8941800c 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -10,6 +10,5 @@ jobs: - uses: errata-ai/vale-action@reviewdog with: files: content - with: # github-pr-check, github-pr-review, github-check reporter: github-pr-check \ No newline at end of file From 8f8bedefa3b42d2d6fa59cc16eb39e7f7ff6885f Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 12 Sep 2024 17:52:31 +0300 Subject: [PATCH 10/74] Adding the first batch of allowed words Signed-off-by: Gergely Csatari --- .../config/vocabularies/Nephio/accept.txt | 51 +++++++++++++++++++ .github/workflows/proofreading-vale.yml | 2 +- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 .github/.vale/config/vocabularies/Nephio/accept.txt diff --git a/.github/.vale/config/vocabularies/Nephio/accept.txt b/.github/.vale/config/vocabularies/Nephio/accept.txt new file mode 100644 index 00000000..0e4f8036 --- /dev/null +++ b/.github/.vale/config/vocabularies/Nephio/accept.txt @@ -0,0 +1,51 @@ +# Accepted words (other acronyms must be explained) +API +APIs +apiserver +ASN +ASNs +[Aa]utoscaling +cabundle +[Cc]onfigmap +CLI +CRD +CRDs +Dockerfile +[Ee]tcd +gcloud +Gitea +GitHub +GitLab +Graphviz +[Hh]omebrew +[Kk]pt +[Kk]ptfile +kubectl +Kubernetes +[Nn]amespace +Nephio +NF +NFDeploy +NFDeployment +NFs +[Mm]akefile +Multus +OCI +[Oo]nboarding +parameterRef +passwordless +[Pp]kgserver +[Pp]orch +[Pp]orchctl +[Rr]pkg +stdout +stderr +sudo +TLS +[Tt]riage +[Tt]ko +[Uu]ntar +VM +VMs +VSCode +VSphere \ No newline at end of file diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 8941800c..efb49bdc 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -6,7 +6,7 @@ jobs: name: runner / vale runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: errata-ai/vale-action@reviewdog with: files: content From bd2867a2381aa2e45b72730074a534fd0ccfbfae Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 12 Sep 2024 17:58:35 +0300 Subject: [PATCH 11/74] Configuring the vocabluary Signed-off-by: Gergely Csatari --- .vale.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale.ini b/.vale.ini index 16554a08..4bcb9d18 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,6 @@ StylesPath = .github\.vale MinAlertLevel = suggestion +Vocab = Nephio [*.md] BasedOnStyles = Vale \ No newline at end of file From 219975ff2a9c7b1b4fb24b33bf89dbbdb57c716f Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 07:43:16 +0300 Subject: [PATCH 12/74] Fxing vale config Signed-off-by: Gergely Csatari --- .../.vale/config/vocabularies/TODO/accept.txt | 65 ------------------- .vale.ini | 14 +++- 2 files changed, 12 insertions(+), 67 deletions(-) delete mode 100644 .github/.vale/config/vocabularies/TODO/accept.txt diff --git a/.github/.vale/config/vocabularies/TODO/accept.txt b/.github/.vale/config/vocabularies/TODO/accept.txt deleted file mode 100644 index 5b0b462d..00000000 --- a/.github/.vale/config/vocabularies/TODO/accept.txt +++ /dev/null @@ -1,65 +0,0 @@ -# Accepted words (other acronyms must be explained) -CEOs? -CFOs? -InnerSource -NGOs? -OSPOs? -SBOMs? -TODO -Whitepaper -deliverables -libre - -# Author names -Alin -Aniszczyk -Annania -Ashish -Bogaard -Brasseur -Chitale -Coughlan -Csatari -Fukuchi -Gergely -Hendriks -Hiro -Hoving -Ibrahim -Ildiko -Jeroen -Jerpelea -Jiri -Khalaf -Khalil -Koymans -Kuwata -Lieggi -Maltzhan -Marek -Marz -Masae -Masayuki -Melaku -Moffat -Remy -Saebi -Scheerder -Seo -Shida -Shilla -Supriya -Takanori -Ulises -Vancsa -Xie -Yehuda -Yeon - -# Company names -Autodesk -Comcast -Qiita -Synopsys -Uber -VMware diff --git a/.vale.ini b/.vale.ini index 4bcb9d18..7ba54a35 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,6 +1,16 @@ -StylesPath = .github\.vale +# Vale is an open-source, command-line tool that brings your editorial style guide to life. +# source: https://vale.sh + +# Styles are stored in the .github/.vale folder +StylesPath = .github/.vale + +# Configured styles can be downloaded with the command: vale sync +Packages = proselint, alex, Hugo +# Alert suggestions, warnings and alerts MinAlertLevel = suggestion + +# Configure a dictionary specific to Nephio Vocab = Nephio [*.md] -BasedOnStyles = Vale \ No newline at end of file +BasedOnStyles = Vale, proselint, alex \ No newline at end of file From c14f24496090dead7d3d5f05f0f69ffd5c4a9db4 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 07:50:45 +0300 Subject: [PATCH 13/74] Enable manual trigger Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index efb49bdc..082641ef 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -1,5 +1,7 @@ name: reviewdog -on: [pull_request] +on: + pull_request: + workflow_dispatch: jobs: vale: From 5f83eee7dfb5a4d6d05a5b62412b3fe1d0cf5c6e Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 08:03:11 +0300 Subject: [PATCH 14/74] Moving the .vale folder to the repo root Signed-off-by: Gergely Csatari --- .vale/.vale-config/2-Hugo.ini | 10 ++++++++++ {.github/.vale => .vale}/alex/Ablist.yml | 0 {.github/.vale => .vale}/alex/Condescending.yml | 0 {.github/.vale => .vale}/alex/Gendered.yml | 0 {.github/.vale => .vale}/alex/LGBTQ.yml | 0 {.github/.vale => .vale}/alex/Press.yml | 0 {.github/.vale => .vale}/alex/ProfanityLikely.yml | 0 {.github/.vale => .vale}/alex/ProfanityMaybe.yml | 0 {.github/.vale => .vale}/alex/ProfanityUnlikely.yml | 0 {.github/.vale => .vale}/alex/README.md | 0 {.github/.vale => .vale}/alex/Race.yml | 0 {.github/.vale => .vale}/alex/Suicide.yml | 0 {.github/.vale => .vale}/alex/meta.json | 0 .../config/vocabularies/Nephio/accept.txt | 0 {.github/.vale => .vale}/proselint/Airlinese.yml | 0 {.github/.vale => .vale}/proselint/AnimalLabels.yml | 0 {.github/.vale => .vale}/proselint/Annotations.yml | 0 {.github/.vale => .vale}/proselint/Apologizing.yml | 0 {.github/.vale => .vale}/proselint/Archaisms.yml | 0 {.github/.vale => .vale}/proselint/But.yml | 0 {.github/.vale => .vale}/proselint/Cliches.yml | 0 {.github/.vale => .vale}/proselint/CorporateSpeak.yml | 0 {.github/.vale => .vale}/proselint/Currency.yml | 0 {.github/.vale => .vale}/proselint/Cursing.yml | 0 {.github/.vale => .vale}/proselint/DateCase.yml | 0 {.github/.vale => .vale}/proselint/DateMidnight.yml | 0 {.github/.vale => .vale}/proselint/DateRedundancy.yml | 0 {.github/.vale => .vale}/proselint/DateSpacing.yml | 0 {.github/.vale => .vale}/proselint/DenizenLabels.yml | 0 {.github/.vale => .vale}/proselint/Diacritical.yml | 0 {.github/.vale => .vale}/proselint/GenderBias.yml | 0 {.github/.vale => .vale}/proselint/GroupTerms.yml | 0 {.github/.vale => .vale}/proselint/Hedging.yml | 0 {.github/.vale => .vale}/proselint/Hyperbole.yml | 0 {.github/.vale => .vale}/proselint/Jargon.yml | 0 {.github/.vale => .vale}/proselint/LGBTOffensive.yml | 0 {.github/.vale => .vale}/proselint/LGBTTerms.yml | 0 {.github/.vale => .vale}/proselint/Malapropisms.yml | 0 {.github/.vale => .vale}/proselint/Needless.yml | 0 {.github/.vale => .vale}/proselint/Nonwords.yml | 0 {.github/.vale => .vale}/proselint/Oxymorons.yml | 0 {.github/.vale => .vale}/proselint/P-Value.yml | 0 {.github/.vale => .vale}/proselint/RASSyndrome.yml | 0 {.github/.vale => .vale}/proselint/README.md | 0 {.github/.vale => .vale}/proselint/Skunked.yml | 0 {.github/.vale => .vale}/proselint/Spelling.yml | 0 {.github/.vale => .vale}/proselint/Typography.yml | 0 {.github/.vale => .vale}/proselint/Uncomparables.yml | 0 {.github/.vale => .vale}/proselint/Very.yml | 0 {.github/.vale => .vale}/proselint/meta.json | 0 50 files changed, 10 insertions(+) create mode 100644 .vale/.vale-config/2-Hugo.ini rename {.github/.vale => .vale}/alex/Ablist.yml (100%) rename {.github/.vale => .vale}/alex/Condescending.yml (100%) rename {.github/.vale => .vale}/alex/Gendered.yml (100%) rename {.github/.vale => .vale}/alex/LGBTQ.yml (100%) rename {.github/.vale => .vale}/alex/Press.yml (100%) rename {.github/.vale => .vale}/alex/ProfanityLikely.yml (100%) rename {.github/.vale => .vale}/alex/ProfanityMaybe.yml (100%) rename {.github/.vale => .vale}/alex/ProfanityUnlikely.yml (100%) rename {.github/.vale => .vale}/alex/README.md (100%) rename {.github/.vale => .vale}/alex/Race.yml (100%) rename {.github/.vale => .vale}/alex/Suicide.yml (100%) rename {.github/.vale => .vale}/alex/meta.json (100%) rename {.github/.vale => .vale}/config/vocabularies/Nephio/accept.txt (100%) rename {.github/.vale => .vale}/proselint/Airlinese.yml (100%) rename {.github/.vale => .vale}/proselint/AnimalLabels.yml (100%) rename {.github/.vale => .vale}/proselint/Annotations.yml (100%) rename {.github/.vale => .vale}/proselint/Apologizing.yml (100%) rename {.github/.vale => .vale}/proselint/Archaisms.yml (100%) rename {.github/.vale => .vale}/proselint/But.yml (100%) rename {.github/.vale => .vale}/proselint/Cliches.yml (100%) rename {.github/.vale => .vale}/proselint/CorporateSpeak.yml (100%) rename {.github/.vale => .vale}/proselint/Currency.yml (100%) rename {.github/.vale => .vale}/proselint/Cursing.yml (100%) rename {.github/.vale => .vale}/proselint/DateCase.yml (100%) rename {.github/.vale => .vale}/proselint/DateMidnight.yml (100%) rename {.github/.vale => .vale}/proselint/DateRedundancy.yml (100%) rename {.github/.vale => .vale}/proselint/DateSpacing.yml (100%) rename {.github/.vale => .vale}/proselint/DenizenLabels.yml (100%) rename {.github/.vale => .vale}/proselint/Diacritical.yml (100%) rename {.github/.vale => .vale}/proselint/GenderBias.yml (100%) rename {.github/.vale => .vale}/proselint/GroupTerms.yml (100%) rename {.github/.vale => .vale}/proselint/Hedging.yml (100%) rename {.github/.vale => .vale}/proselint/Hyperbole.yml (100%) rename {.github/.vale => .vale}/proselint/Jargon.yml (100%) rename {.github/.vale => .vale}/proselint/LGBTOffensive.yml (100%) rename {.github/.vale => .vale}/proselint/LGBTTerms.yml (100%) rename {.github/.vale => .vale}/proselint/Malapropisms.yml (100%) rename {.github/.vale => .vale}/proselint/Needless.yml (100%) rename {.github/.vale => .vale}/proselint/Nonwords.yml (100%) rename {.github/.vale => .vale}/proselint/Oxymorons.yml (100%) rename {.github/.vale => .vale}/proselint/P-Value.yml (100%) rename {.github/.vale => .vale}/proselint/RASSyndrome.yml (100%) rename {.github/.vale => .vale}/proselint/README.md (100%) rename {.github/.vale => .vale}/proselint/Skunked.yml (100%) rename {.github/.vale => .vale}/proselint/Spelling.yml (100%) rename {.github/.vale => .vale}/proselint/Typography.yml (100%) rename {.github/.vale => .vale}/proselint/Uncomparables.yml (100%) rename {.github/.vale => .vale}/proselint/Very.yml (100%) rename {.github/.vale => .vale}/proselint/meta.json (100%) diff --git a/.vale/.vale-config/2-Hugo.ini b/.vale/.vale-config/2-Hugo.ini new file mode 100644 index 00000000..b0d6257d --- /dev/null +++ b/.vale/.vale-config/2-Hugo.ini @@ -0,0 +1,10 @@ +[*.md] +# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) +TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ +(\[.+\]\({{< .+ >}}\)), \ +({{[%<] .+ [%>]}}) + +# Exclude `{{< myshortcode `This is some HTML, ... >}}` +BlockIgnores = (?sm)^({{[%<] [^{]*? [%>]}})\n$, \ +(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ +({{[%<] .+ [%>]}}) diff --git a/.github/.vale/alex/Ablist.yml b/.vale/alex/Ablist.yml similarity index 100% rename from .github/.vale/alex/Ablist.yml rename to .vale/alex/Ablist.yml diff --git a/.github/.vale/alex/Condescending.yml b/.vale/alex/Condescending.yml similarity index 100% rename from .github/.vale/alex/Condescending.yml rename to .vale/alex/Condescending.yml diff --git a/.github/.vale/alex/Gendered.yml b/.vale/alex/Gendered.yml similarity index 100% rename from .github/.vale/alex/Gendered.yml rename to .vale/alex/Gendered.yml diff --git a/.github/.vale/alex/LGBTQ.yml b/.vale/alex/LGBTQ.yml similarity index 100% rename from .github/.vale/alex/LGBTQ.yml rename to .vale/alex/LGBTQ.yml diff --git a/.github/.vale/alex/Press.yml b/.vale/alex/Press.yml similarity index 100% rename from .github/.vale/alex/Press.yml rename to .vale/alex/Press.yml diff --git a/.github/.vale/alex/ProfanityLikely.yml b/.vale/alex/ProfanityLikely.yml similarity index 100% rename from .github/.vale/alex/ProfanityLikely.yml rename to .vale/alex/ProfanityLikely.yml diff --git a/.github/.vale/alex/ProfanityMaybe.yml b/.vale/alex/ProfanityMaybe.yml similarity index 100% rename from .github/.vale/alex/ProfanityMaybe.yml rename to .vale/alex/ProfanityMaybe.yml diff --git a/.github/.vale/alex/ProfanityUnlikely.yml b/.vale/alex/ProfanityUnlikely.yml similarity index 100% rename from .github/.vale/alex/ProfanityUnlikely.yml rename to .vale/alex/ProfanityUnlikely.yml diff --git a/.github/.vale/alex/README.md b/.vale/alex/README.md similarity index 100% rename from .github/.vale/alex/README.md rename to .vale/alex/README.md diff --git a/.github/.vale/alex/Race.yml b/.vale/alex/Race.yml similarity index 100% rename from .github/.vale/alex/Race.yml rename to .vale/alex/Race.yml diff --git a/.github/.vale/alex/Suicide.yml b/.vale/alex/Suicide.yml similarity index 100% rename from .github/.vale/alex/Suicide.yml rename to .vale/alex/Suicide.yml diff --git a/.github/.vale/alex/meta.json b/.vale/alex/meta.json similarity index 100% rename from .github/.vale/alex/meta.json rename to .vale/alex/meta.json diff --git a/.github/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt similarity index 100% rename from .github/.vale/config/vocabularies/Nephio/accept.txt rename to .vale/config/vocabularies/Nephio/accept.txt diff --git a/.github/.vale/proselint/Airlinese.yml b/.vale/proselint/Airlinese.yml similarity index 100% rename from .github/.vale/proselint/Airlinese.yml rename to .vale/proselint/Airlinese.yml diff --git a/.github/.vale/proselint/AnimalLabels.yml b/.vale/proselint/AnimalLabels.yml similarity index 100% rename from .github/.vale/proselint/AnimalLabels.yml rename to .vale/proselint/AnimalLabels.yml diff --git a/.github/.vale/proselint/Annotations.yml b/.vale/proselint/Annotations.yml similarity index 100% rename from .github/.vale/proselint/Annotations.yml rename to .vale/proselint/Annotations.yml diff --git a/.github/.vale/proselint/Apologizing.yml b/.vale/proselint/Apologizing.yml similarity index 100% rename from .github/.vale/proselint/Apologizing.yml rename to .vale/proselint/Apologizing.yml diff --git a/.github/.vale/proselint/Archaisms.yml b/.vale/proselint/Archaisms.yml similarity index 100% rename from .github/.vale/proselint/Archaisms.yml rename to .vale/proselint/Archaisms.yml diff --git a/.github/.vale/proselint/But.yml b/.vale/proselint/But.yml similarity index 100% rename from .github/.vale/proselint/But.yml rename to .vale/proselint/But.yml diff --git a/.github/.vale/proselint/Cliches.yml b/.vale/proselint/Cliches.yml similarity index 100% rename from .github/.vale/proselint/Cliches.yml rename to .vale/proselint/Cliches.yml diff --git a/.github/.vale/proselint/CorporateSpeak.yml b/.vale/proselint/CorporateSpeak.yml similarity index 100% rename from .github/.vale/proselint/CorporateSpeak.yml rename to .vale/proselint/CorporateSpeak.yml diff --git a/.github/.vale/proselint/Currency.yml b/.vale/proselint/Currency.yml similarity index 100% rename from .github/.vale/proselint/Currency.yml rename to .vale/proselint/Currency.yml diff --git a/.github/.vale/proselint/Cursing.yml b/.vale/proselint/Cursing.yml similarity index 100% rename from .github/.vale/proselint/Cursing.yml rename to .vale/proselint/Cursing.yml diff --git a/.github/.vale/proselint/DateCase.yml b/.vale/proselint/DateCase.yml similarity index 100% rename from .github/.vale/proselint/DateCase.yml rename to .vale/proselint/DateCase.yml diff --git a/.github/.vale/proselint/DateMidnight.yml b/.vale/proselint/DateMidnight.yml similarity index 100% rename from .github/.vale/proselint/DateMidnight.yml rename to .vale/proselint/DateMidnight.yml diff --git a/.github/.vale/proselint/DateRedundancy.yml b/.vale/proselint/DateRedundancy.yml similarity index 100% rename from .github/.vale/proselint/DateRedundancy.yml rename to .vale/proselint/DateRedundancy.yml diff --git a/.github/.vale/proselint/DateSpacing.yml b/.vale/proselint/DateSpacing.yml similarity index 100% rename from .github/.vale/proselint/DateSpacing.yml rename to .vale/proselint/DateSpacing.yml diff --git a/.github/.vale/proselint/DenizenLabels.yml b/.vale/proselint/DenizenLabels.yml similarity index 100% rename from .github/.vale/proselint/DenizenLabels.yml rename to .vale/proselint/DenizenLabels.yml diff --git a/.github/.vale/proselint/Diacritical.yml b/.vale/proselint/Diacritical.yml similarity index 100% rename from .github/.vale/proselint/Diacritical.yml rename to .vale/proselint/Diacritical.yml diff --git a/.github/.vale/proselint/GenderBias.yml b/.vale/proselint/GenderBias.yml similarity index 100% rename from .github/.vale/proselint/GenderBias.yml rename to .vale/proselint/GenderBias.yml diff --git a/.github/.vale/proselint/GroupTerms.yml b/.vale/proselint/GroupTerms.yml similarity index 100% rename from .github/.vale/proselint/GroupTerms.yml rename to .vale/proselint/GroupTerms.yml diff --git a/.github/.vale/proselint/Hedging.yml b/.vale/proselint/Hedging.yml similarity index 100% rename from .github/.vale/proselint/Hedging.yml rename to .vale/proselint/Hedging.yml diff --git a/.github/.vale/proselint/Hyperbole.yml b/.vale/proselint/Hyperbole.yml similarity index 100% rename from .github/.vale/proselint/Hyperbole.yml rename to .vale/proselint/Hyperbole.yml diff --git a/.github/.vale/proselint/Jargon.yml b/.vale/proselint/Jargon.yml similarity index 100% rename from .github/.vale/proselint/Jargon.yml rename to .vale/proselint/Jargon.yml diff --git a/.github/.vale/proselint/LGBTOffensive.yml b/.vale/proselint/LGBTOffensive.yml similarity index 100% rename from .github/.vale/proselint/LGBTOffensive.yml rename to .vale/proselint/LGBTOffensive.yml diff --git a/.github/.vale/proselint/LGBTTerms.yml b/.vale/proselint/LGBTTerms.yml similarity index 100% rename from .github/.vale/proselint/LGBTTerms.yml rename to .vale/proselint/LGBTTerms.yml diff --git a/.github/.vale/proselint/Malapropisms.yml b/.vale/proselint/Malapropisms.yml similarity index 100% rename from .github/.vale/proselint/Malapropisms.yml rename to .vale/proselint/Malapropisms.yml diff --git a/.github/.vale/proselint/Needless.yml b/.vale/proselint/Needless.yml similarity index 100% rename from .github/.vale/proselint/Needless.yml rename to .vale/proselint/Needless.yml diff --git a/.github/.vale/proselint/Nonwords.yml b/.vale/proselint/Nonwords.yml similarity index 100% rename from .github/.vale/proselint/Nonwords.yml rename to .vale/proselint/Nonwords.yml diff --git a/.github/.vale/proselint/Oxymorons.yml b/.vale/proselint/Oxymorons.yml similarity index 100% rename from .github/.vale/proselint/Oxymorons.yml rename to .vale/proselint/Oxymorons.yml diff --git a/.github/.vale/proselint/P-Value.yml b/.vale/proselint/P-Value.yml similarity index 100% rename from .github/.vale/proselint/P-Value.yml rename to .vale/proselint/P-Value.yml diff --git a/.github/.vale/proselint/RASSyndrome.yml b/.vale/proselint/RASSyndrome.yml similarity index 100% rename from .github/.vale/proselint/RASSyndrome.yml rename to .vale/proselint/RASSyndrome.yml diff --git a/.github/.vale/proselint/README.md b/.vale/proselint/README.md similarity index 100% rename from .github/.vale/proselint/README.md rename to .vale/proselint/README.md diff --git a/.github/.vale/proselint/Skunked.yml b/.vale/proselint/Skunked.yml similarity index 100% rename from .github/.vale/proselint/Skunked.yml rename to .vale/proselint/Skunked.yml diff --git a/.github/.vale/proselint/Spelling.yml b/.vale/proselint/Spelling.yml similarity index 100% rename from .github/.vale/proselint/Spelling.yml rename to .vale/proselint/Spelling.yml diff --git a/.github/.vale/proselint/Typography.yml b/.vale/proselint/Typography.yml similarity index 100% rename from .github/.vale/proselint/Typography.yml rename to .vale/proselint/Typography.yml diff --git a/.github/.vale/proselint/Uncomparables.yml b/.vale/proselint/Uncomparables.yml similarity index 100% rename from .github/.vale/proselint/Uncomparables.yml rename to .vale/proselint/Uncomparables.yml diff --git a/.github/.vale/proselint/Very.yml b/.vale/proselint/Very.yml similarity index 100% rename from .github/.vale/proselint/Very.yml rename to .vale/proselint/Very.yml diff --git a/.github/.vale/proselint/meta.json b/.vale/proselint/meta.json similarity index 100% rename from .github/.vale/proselint/meta.json rename to .vale/proselint/meta.json From b5301a391121868bd66ea88858bfd5221c8581f4 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 08:24:41 +0300 Subject: [PATCH 15/74] Adding a token and changing config Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 3 ++- .vale.ini | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 082641ef..73de371d 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -13,4 +13,5 @@ jobs: with: files: content # github-pr-check, github-pr-review, github-check - reporter: github-pr-check \ No newline at end of file + reporter: github-pr-check + token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file diff --git a/.vale.ini b/.vale.ini index 7ba54a35..95679aba 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,8 +1,8 @@ # Vale is an open-source, command-line tool that brings your editorial style guide to life. # source: https://vale.sh -# Styles are stored in the .github/.vale folder -StylesPath = .github/.vale +# Styles are stored in the .vale folder +StylesPath = .vale # Configured styles can be downloaded with the command: vale sync Packages = proselint, alex, Hugo From 75aab61ad566cfef8f30cc61fb2f854c1b26c718 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 08:34:56 +0300 Subject: [PATCH 16/74] Checking all files Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 73de371d..ee13b26e 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -11,7 +11,7 @@ jobs: - uses: actions/checkout@v4 - uses: errata-ai/vale-action@reviewdog with: - files: content + files: all # github-pr-check, github-pr-review, github-check reporter: github-pr-check token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file From 8fafceb6589397eb4a590e1c96b8afbdc6716811 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 09:39:15 +0300 Subject: [PATCH 17/74] Addig todo to annotations Signed-off-by: Gergely Csatari --- .vale/proselint/Annotations.yml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.vale/proselint/Annotations.yml b/.vale/proselint/Annotations.yml index 83d9435c..f3f21bae 100644 --- a/.vale/proselint/Annotations.yml +++ b/.vale/proselint/Annotations.yml @@ -6,3 +6,6 @@ tokens: - XXX - FIXME - NOTE + - TODO + - Todo + - todo From 2309b32cf984db3cb149532482d1fe38cee25f32 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:00:06 +0300 Subject: [PATCH 18/74] Hopefully adding the corect token Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index ee13b26e..6349761c 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -14,4 +14,4 @@ jobs: files: all # github-pr-check, github-pr-review, github-check reporter: github-pr-check - token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file + token: ${{secrets.GITHUB_TOKEN}} \ No newline at end of file From 12ff4b7fd1dc484736438c8af72cc6bbe573a73f Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:07:53 +0300 Subject: [PATCH 19/74] Limiting to the places where the content is Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 6349761c..8af50f15 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -11,7 +11,7 @@ jobs: - uses: actions/checkout@v4 - uses: errata-ai/vale-action@reviewdog with: - files: all + files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check reporter: github-pr-check token: ${{secrets.GITHUB_TOKEN}} \ No newline at end of file From 0b3d49e9fa8b634bf421a1350b8e7452b6d625b4 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:21:56 +0300 Subject: [PATCH 20/74] Ignoring Hugo control tokens Signed-off-by: Gergely Csatari --- .vale.ini | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 95679aba..7d6d7c00 100644 --- a/.vale.ini +++ b/.vale.ini @@ -13,4 +13,15 @@ MinAlertLevel = suggestion Vocab = Nephio [*.md] -BasedOnStyles = Vale, proselint, alex \ No newline at end of file +BasedOnStyles = Vale, proselint, alex + +# based on https://github.com/errata-ai/Hugo/blob/main/Hugo/.vale.ini +# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) +TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ +(\[.+\]\({{< .+ >}}\)), \ +[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \ +[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s + +# Exclude `{{< myshortcode `This is some HTML, ... >}}` +BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \ +(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) \ No newline at end of file From df2621345f912361dcdd695fe986af9ebaac3fce Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:24:11 +0300 Subject: [PATCH 21/74] Changig tokens Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 8af50f15..00faa900 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -9,9 +9,14 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + - uses: tibdex/github-app-token@v2 + id: generate-token + with: + app_id: ${{ secrets.HELPER_APP_ID }} + private_key: ${{ secrets.HELPER_APP_KEY }} - uses: errata-ai/vale-action@reviewdog with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check reporter: github-pr-check - token: ${{secrets.GITHUB_TOKEN}} \ No newline at end of file + token: ${{ steps.generate-token.outputs.token }} \ No newline at end of file From f300756b48995b863a3fe710c076ff7761728ab0 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:30:29 +0300 Subject: [PATCH 22/74] Adding name to action steps Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 00faa900..545d2e65 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -8,13 +8,18 @@ jobs: name: runner / vale runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 - - uses: tibdex/github-app-token@v2 + - name: Checkout + uses: actions/checkout@v4 + + - name: Generate ephemeral token + uses: tibdex/github-app-token@v2 id: generate-token with: app_id: ${{ secrets.HELPER_APP_ID }} private_key: ${{ secrets.HELPER_APP_KEY }} - - uses: errata-ai/vale-action@reviewdog + + - name: Run Vale + uses: errata-ai/vale-action@reviewdog with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check From 90ce00598fa61ab13efbed0b0748f58354c67953 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 13 Sep 2024 10:35:34 +0300 Subject: [PATCH 23/74] Fixing token generation Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 545d2e65..2875923d 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -11,8 +11,7 @@ jobs: - name: Checkout uses: actions/checkout@v4 - - name: Generate ephemeral token - uses: tibdex/github-app-token@v2 + - uses: tibdex/github-app-token@v2 id: generate-token with: app_id: ${{ secrets.HELPER_APP_ID }} From 389f9f5fa660bcd0d5104b4ed0bac6cff994fed9 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Wed, 18 Sep 2024 11:00:51 +0300 Subject: [PATCH 24/74] Apply suggestions from code review Co-authored-by: Rado Chmiel --- .github/workflows/proofreading-vale.yml | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 2875923d..646ce991 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -9,18 +9,19 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - - uses: tibdex/github-app-token@v2 - id: generate-token + + - name: Harden Runner + uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1 with: - app_id: ${{ secrets.HELPER_APP_ID }} - private_key: ${{ secrets.HELPER_APP_KEY }} + egress-policy: audit + - name: Run Vale - uses: errata-ai/vale-action@reviewdog + uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check reporter: github-pr-check - token: ${{ steps.generate-token.outputs.token }} \ No newline at end of file + token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file From 7c723c34efd9bacd11889febcdbdcb0124a4ddf5 Mon Sep 17 00:00:00 2001 From: Schweier Dominika Date: Wed, 18 Sep 2024 17:22:22 +0200 Subject: [PATCH 25/74] Inline commands (#171) Fixed in-line commands --------- Signed-off-by: Schweier Dominika Signed-off-by: Dominika Schweier --- content/en/docs/guides/install-guides/_index.md | 2 +- .../docs/guides/install-guides/explore-sandbox.md | 4 ++-- .../install-guides/package-transformations.md | 14 ++++++-------- .../docs/guides/user-guides/exercise-1-free5gc.md | 4 ++-- .../en/docs/guides/user-guides/exercise-2-oai.md | 2 +- .../porch/contributors-guide/environment-setup.md | 2 +- .../en/docs/porch/running-porch/running-on-GKE.md | 9 +++------ 7 files changed, 16 insertions(+), 21 deletions(-) diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md index 93decc12..872bf863 100644 --- a/content/en/docs/guides/install-guides/_index.md +++ b/content/en/docs/guides/install-guides/_index.md @@ -133,7 +133,7 @@ The following environment variables can be used to configure the installation: Monitor the installation on your terminal. -Log onto your VM using ssh on another terminal and use commands *docker* and *kubectl* to monitor the installation. +Log onto your VM using ssh on another terminal and use commands `docker` and `kubectl` to monitor the installation. ## Access to the User Interfaces diff --git a/content/en/docs/guides/install-guides/explore-sandbox.md b/content/en/docs/guides/install-guides/explore-sandbox.md index c17c1c06..2bd89bdf 100644 --- a/content/en/docs/guides/install-guides/explore-sandbox.md +++ b/content/en/docs/guides/install-guides/explore-sandbox.md @@ -34,7 +34,7 @@ Everything is installed on the Management KinD cluster by Ansible scripts using The install unpacks each kpt package in the */tmp* directory. It then applies the kpt functions to the packages and applies the packages to the Management KinD cluster. This allows the user to check the status of the kpt packages in -the cluster using the *kpt live status* command on the unpacked packages in the */tmp* directory. +the cluster using the `kpt live status` command on the unpacked packages in the */tmp* directory. The rendered kpt packages containing components are unpacked in the */tmp/kpt-pkg* directory. The rendered kpt packages that create the *mgmt* and *mgmt-staging* repositories are unpacked in the */tmp/repository* directory. The rendered kpt @@ -58,7 +58,7 @@ You can examine the contents of any rendered kpt packager by examining the conte └── resource-backend ``` -You can check the status of an applied kpt package using a "kpt live status package_dir" command. +You can check the status of an applied kpt package using a `kpt live status package_dir` command. ```bash kpt live status /tmp/kpt-pkg/nephio-controllers/ diff --git a/content/en/docs/guides/install-guides/package-transformations.md b/content/en/docs/guides/install-guides/package-transformations.md index 90149abf..8819cc45 100644 --- a/content/en/docs/guides/install-guides/package-transformations.md +++ b/content/en/docs/guides/install-guides/package-transformations.md @@ -192,9 +192,7 @@ mgmt-staging git Package false True http://172.18.0. nephio-example-packages git Package false True https://github.com/nephio-project/nephio-example-packages.git ``` -To see all the remote packages that are available: - -$ porchctl rpkg get +To see all the remote packages that are available use the `$ porchctl rpkg get` command. ```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY @@ -297,12 +295,12 @@ NAME PACKAGE WORKSPACENAME REVISION L mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional v1 false Draft mgmt ``` -2. Pull the package to get a local copy of it +2. Pull the package to get a local copy of it: ```bash porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional ``` -3. Set the Nephio labels on the package +3. Set the Nephio labels on the package: ```bash kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site-type=regional" "nephio.org/region=us-west1" @@ -379,16 +377,16 @@ The `PackageVariant` specified in `pv-cluster.yaml` is executed and: package called `lambda-cluster` in the gitea `mgmt` repository on your management cluster. 2. Applies the `lambda-cluster` kpt package to create the kind cluster for the - workload cluster + workload cluster. #### Package transformations During creation of the package variant kpt package, the following transformations occur: 1. It creates a `drafts/lambda-cluster/v1` branch on the `mgmt` repository -2. It does the equivalent of a [kpt pkg get](#kpt-pkg-get) on the `cluster-capi-kind` package into a directory called +2. It does the equivalent of a [`kpt pkg get`](#kpt-pkg-get) on the `cluster-capi-kind` package into a directory called `lambda-cluster` on that branch, with the same transformations on package files carried out as the - [kpt pkg get](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit + [`kpt pkg get`](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit 3. The pipeline specified in the `Kptfile`of the `cluster-capi-kind` package specifies an `apply-replacements` specified in the `apply-replacements.yaml` file in the package and uses the value of the `workload-cluster.yaml:spec.clusterName` field set in 2. above (which is the workload cluster name). This has the diff --git a/content/en/docs/guides/user-guides/exercise-1-free5gc.md b/content/en/docs/guides/user-guides/exercise-1-free5gc.md index dda3c679..8025bcb9 100644 --- a/content/en/docs/guides/user-guides/exercise-1-free5gc.md +++ b/content/en/docs/guides/user-guides/exercise-1-free5gc.md @@ -786,7 +786,7 @@ kubectl apply -f test-infra/e2e/tests/free5gc/007-edge01-ueransim.yaml ``` You can check to see if the simulated UE is up and running by checking the UERANSIM deployment. First, you can use the -get_capi_kubeconfig` shortcut to retrieve the kubeconfig for the edge01 cluster, and then query that cluster for the +`get_capi_kubeconfig` shortcut to retrieve the kubeconfig for the edge01 cluster, and then query that cluster for the UERANSIM pods. ```bash @@ -927,7 +927,7 @@ The output is similar to: ``` -Observe the changes to the UPF configuration using the kpt pkg diff command. +Observe the changes to the UPF configuration using the `kpt pkg diff` command. ```bash kpt pkg diff /tmp/upf-scale-package | grep linkThroughput diff --git a/content/en/docs/guides/user-guides/exercise-2-oai.md b/content/en/docs/guides/user-guides/exercise-2-oai.md index 5ec0464a..cf7b90a8 100644 --- a/content/en/docs/guides/user-guides/exercise-2-oai.md +++ b/content/en/docs/guides/user-guides/exercise-2-oai.md @@ -356,7 +356,7 @@ packagevariant.config.porch.kpt.dev/oai-ran-operator-regional created ## Step 4: Check Database and Operator Deployment -Within five minutes of applying the RAN, Core Operator, and database Packages, you should see `oai-core` and `oai-cn-operators` namespaces on the Core workload cluster, : +Within five minutes of applying the RAN, Core Operator, and database Packages, you should see `oai-core` and `oai-cn-operators` namespaces on the Core workload cluster: ```bash kubectl get ns --context core-admin@core diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 0e944dd8..3e86ea77 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -127,7 +127,7 @@ packages porch.kpt.dev/v1alpha1 To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../using-porch/install-and-using-porch.md) tutorial to create the repositories in Porch. -You will notice logging messages in VSCode when you run the command `kubectl apply -f porch-repositories.yaml` command. +You will notice logging messages in VSCode when you run the `kubectl apply -f porch-repositories.yaml` command. You can check that your locally running Porch server has created the repositories by running the `porchctl` command: diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index f7354079..0c19468b 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -129,17 +129,14 @@ git clone https://github.com/GoogleContainerTools/kpt.git "${GOPATH}/src/github. repository. If your use case doesn't require Porch to interact with GCP container registries, you can build and deploy Porch by -running the following command. It will build and push Porch Docker images into (by default) Google Container Registry -named (example shown is the Porch server image): - -`gcr.io/YOUR-PROJECT-ID/porch-server:SHORT-COMMIT-SHA` - +running the `gcr.io/YOUR-PROJECT-ID/porch-server:SHORT-COMMIT-SHA` command. It will build and push Porch Docker images into (by default) Google Container Registry +named (example shown is the Porch server image). ```bash IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa ``` -If you want to use different repository, you can set `IMAGE_REPO` variable +If you want to use a different repository, you can set `IMAGE_REPO` variable (see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L32) for details). The `make push-and-deploy-no-sa` target will install Porch but not Config Sync. You can install Config Sync in your k8s From 97376ff79e60ce0f227ab774950ef54b0ba466b5 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 19 Sep 2024 11:18:20 +0300 Subject: [PATCH 26/74] Apply suggestions from code review Co-authored-by: Rado Chmiel --- .github/workflows/proofreading-vale.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 646ce991..f4e37b1f 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -20,6 +20,8 @@ jobs: - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog + env: + REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.VALE_GITHUB_TOKEN }} with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check From 69ca291597a00d36db359c8b9d6aef597f1cb753 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 26 Sep 2024 10:43:17 +0300 Subject: [PATCH 27/74] Update .github/workflows/proofreading-vale.yml Co-authored-by: Rado Chmiel --- .github/workflows/proofreading-vale.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index f4e37b1f..d8500118 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -1,6 +1,8 @@ name: reviewdog on: - pull_request: + pull_request_target: + types: [assigned, opened, edited, ready_for_review] + workflow_dispatch: jobs: From bc652c998fc8c8d50ed044727699a595f2876309 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Thu, 26 Sep 2024 09:57:27 +0200 Subject: [PATCH 28/74] R2 Release Notes language corrections. (#169) Signed-off-by: Michael Greaves --- content/en/docs/release-notes/R2.md | 146 +++++++++++++++------------- 1 file changed, 78 insertions(+), 68 deletions(-) diff --git a/content/en/docs/release-notes/R2.md b/content/en/docs/release-notes/R2.md index 25175e85..2821f9ac 100644 --- a/content/en/docs/release-notes/R2.md +++ b/content/en/docs/release-notes/R2.md @@ -7,17 +7,17 @@ weight: 1 ## Prerequisites -Please refer to the [Install Guide](/content/en/docs/guides/install-guides/install-on-byoc.md#prerequisites) -for the prerequisites on supported environments. +Refer to the [Install Guide](/content/en/docs/guides/install-guides/install-on-byoc.md#prerequisites) +for the prerequisites for supported environments. -## Support Matrix +## Support matrix -The sandbox environment requires a physical or virtual machine with: +The sandbox environment requires a physical or virtual machine with the following: - Ubuntu-20.04-focal or Ubuntu 22.04 Linux Or Fedora 34 -- Minimum 8 cores and Recommended 16 cores (Needed for end-to-end testing with RAN and core ) +- a minimum of eight cores and a recommended 16 cores (these are needed for end-to-end testing with RAN and core) - 32 GB memory - 200 GB disk size -- Default user with sudo passwordless permissions +- a default user with sudo passwordless permissions This installation has been verified on VMs running on Google Cloud. @@ -27,14 +27,17 @@ A Nephio sandbox can be created on any Kubernetes cluster v1.26 and above. ### API -Common CRDs provided for 5G Core and RAN services +Common CRDs are provided for 5G Core and RAN services. ### Web UI -Basic web UI to view and manage the packages and resources within them. +Nephio has a basic web UI to view and manage the packages, and the resources contained in +the packages. ### Packages +The following packages are supported: + * Kpt packages for all [free5GC](https://free5gc.org/) services * Kpt packages for all [OAI](https://openairinterface.org/) services * Packages for the core Nephio services @@ -43,87 +46,94 @@ Basic web UI to view and manage the packages and resources within them. ### Functionalities -* Multi-vendor support +The following functionalities are supported: + +* Multivendor support * API changes * Generalization * Parameterization * Reuse of params -* Multi-cloud support +* Multicloud support * Sandbox * GCP * OpenShift * OAI components - * Deploying OAI 5G Core and RAN Network Functions (CU-CP, CU-UP, RF Simulated DU) - * OAI 5G Core network functions are developed using Python KOPF (Kubernetes Operator Framework) - * End to End call with RF Simulated OAI-NR-UE + * Deploying OAI 5G Core and RAN Network Functions (CU-CP, CU-UP, RF Simulated DU). + * OAI 5G Core network functions are developed using Python Kubernetes Operator Framework (KOPF). + * End-to-end call with RF Simulated OAI-NR-UE. * Integration with new release of Porch - * Porch is now part of Nephio and hosted in Nephio repository. - * Stability - * Security - * Repo watcher changes + * Porch is now part of Nephio and is hosted in the Nephio repository. + * Stability. + * Security. + * Repo watcher changes. * Documentation - * New web based documentation + * New web-based documentation. * Experimental - * Nephio SDK - * Flux-based deployment of Helm charts - * Helm-to-operator converter - * Topology Controller - Northbound API to express the network topology + * Nephio SDK. + * Flux-based deployment of Helm charts. + * Helm-to-operator converter. + * Topology Controller - Northbound API to express the network topology. ### Fixes -* Removing rigid dependency on Gitea -* Upgrading the Multus version -* ConfigMap generator function -* WebUI configuration options for authentication -* Reorganizing the package catalog -* Reduce hard coding of NF parameters -* Stability of end-to-end tests -* Porch improvements -* Documentation enhancements +The following fixes are available: + +* Removing rigid dependency on Gitea. +* Upgrading the Multus version. +* ConfigMap generator function. +* Web UI configuration options for authentication. +* Reorganizing the package catalog. +* Reducing the hard coding of the NF parameters. +* Stability of end-to-end tests. +* Porch improvements. +* Documentation enhancements. ## Limitations -* For infrastructure automation, only creation of KIND clusters is - supported. -* Inter-cluster networking is not dynamic so as more clusters are - deployed, some manual tweaking will be needed for inter-cluster communications. -* Provisioning of VLAN interfaces on nodes is manual at this time. -* Feedback of workload deployments from workload clusters to the Management - cluster is limited. You may need to connect directly to the Workload cluster - via kubectl to debug any deployment issues. -* Web UI features are limited to view/edit of packages and resources in those - packages and their deployment. Additional features will be added - in subsequent releases. -* When the capacities of the UPF,SMF and AMF NFs are changed, the free5GC Operator on the - Workload cluster will instantiate a new POD with correspondingly modified - resources (CPU, memory etc.) During this process, the pod will restart. This is a +The following limitations need to be borne in mind: + +* For infrastructure automation, only the creation of KIND clusters is supported. +* Inter-cluster networking is not dynamic. Therefore, as more clusters are deployed, + some manual tweaking will be needed for inter-cluster communications. +* Provisioning of VLAN interfaces on nodes is currently performed manually. +* Feedback of workload deployments from workload clusters to the management cluster + is limited. You may need to connect directly to the workload cluster via kubectl to + debug any deployment issues. +* Web UI features are limited to the viewing/editing of packages and resources in those + packages and their deployment. Additional features will be added in subsequent releases. +* When the capacities of the UPF, SMF, and AMF NFs are changed, the free5GC Operator on + the workload cluster will instantiate a new POD with correspondingly modified resources + (CPU, memory, and so on). During this process, the POD will restart. This is a limitation of free5GC. -* Only Gitea works with automated cluster provisioning to create new - repositories and join them to Nephio. To use a different Git provider, you - must manually provision cluster repositories, register them to the Nephio - management server, and set up Config Sync on the Workload cluster. -* The WebUI does not require authentication in the current demo configuration. - Testing of the WebUI with authentication configured has not been done at this - time. -* The WebUI only shows resources in the default namespace. -* While many types of Git authentication are supported, the testing was only - done with token-based Git authentication in Gitea. - -## Known Issues and Workarounds - -* Packages may take a long time to be approved by the auto-approval - controller. If they seem stuck, restarting Porch and the Nephio controllers - may help: +* Only Gitea works with automated cluster provisioning to create new repositories and + join them to Nephio. To use a different Git provider, you must manually provision the + cluster repositories, register them to the Nephio management server, and set up Config + Sync on the workload cluster. +* In the current demo configuration, the Web UI does not require authentication. Testing + of the Web UI with authentication configured has not yet been done. +* The Web UI only shows resources in the default namespace. +* While many types of Git authentication are supported, testing has only been done with + token-based Git authentication in Gitea. + +## Known issues and workarounds + +* Packages may take time to be approved by the auto-approval controller. If they appear to have + frozen, it may help to restart Porch and the Nephio controllers using the following commands: ```bash kubectl -n porch-system rollout restart deploy porch-server kubectl -n nephio-system rollout restart deploy nephio-controller ``` -* Occasional calls to `porchctl rpkg copy` may fail with a message like +* Occasional calls to `porchctl rpkg copy` may fail with the following message, or similar: `Error: Internal error occurred: error applying patch: conflict: fragment line - does not match src line`. Try again in a little while, this may clear up on - its own. Restarting Porch may also help. -* During specialization, we may have duplicate parameterRef extensions, leading to failed deployments (wrong configurations are generated). The current workaround is to redeploy the package. The bug is due to NFDeploy reconciliation not being correctly idempotent. - -* The free5GC operator may create duplicate entries in the SMF function configuration. This is harmless, but still incorrect. -* Links in the documentation may not render in Github due to the limitations of the tool being used for web based documentation. + does not match src line`. + If such a message appears, then retry in a little while, as this error may resolve itself. Restarting + Porch may also help. +* During specialization, we may have duplicate parameterRef extensions, leading to failed deployments + (the wrong configurations are generated). The current workaround is to redeploy the package. The bug is + due to the NFDeploy reconciliation not being idempotent. + +* The free5GC operator may create duplicate entries in the SMF function configuration. This will not do + any harm, but is nevertheless incorrect. +* Links in the documentation may not render in Github, due to the limitations of the tool being used for + web-based documentation. From c4347d183c6265c4611a27f52680b3d04fda247c Mon Sep 17 00:00:00 2001 From: Daniel Kostecki <84861140+dkosteck@users.noreply.github.com> Date: Fri, 4 Oct 2024 04:44:35 -0400 Subject: [PATCH 29/74] Update OpenShift install guide with prereqs for basic installation using init.sh (#173) This is a follow up on the work merged in https://github.com/nephio-project/catalog/pull/72, updating the docs to reflect some prereqs needed for OCP. I think the OCP docs are still very much a work in progress, but this should at least make the docs for our contribution more consistent with test-infra and the catalog repos. resolve https://github.com/nephio-project/nephio/issues/801 --- .../guides/install-guides/install-on-openshift.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/en/docs/guides/install-guides/install-on-openshift.md b/content/en/docs/guides/install-guides/install-on-openshift.md index a1015e2b..861b9f78 100644 --- a/content/en/docs/guides/install-guides/install-on-openshift.md +++ b/content/en/docs/guides/install-guides/install-on-openshift.md @@ -54,7 +54,16 @@ Once installed, you need to prepare the management cluster for zero touch provis ## Install Nephio -### OpenShift Package Repository +### Option 1: Using init.sh (as a Pre-installed K8s Cluster) + +If using init.sh directly to deploy Nephio management components, as one would for a generic K8s Cluster, there are some prerequisites to consider: +- A default StorageClass must be configured providing persistent storage for PVCs (for instance through the LVMS Operator and an LVMCluster) +- [Security Context Constraits](https://github.com/nephio-project/catalog/tree/main/distros/openshift/security-context-constraints) must be applied for successful Nephio component deployment + +Follow the steps present in the [Install Guide](/content/en/docs/guides/install-guides/_index.md) for a Pre-installed K8s Cluster to install manaement components + + +### Option 2: Using Blueprints Nephio OpenShift Repo OpenShift Package Repository A repository of OpenShift-installation specific packages must be used to deploy Nephio. This repository contains packages derived from the standard Nephio R1 packages, but with OpenShift-specific modifications. @@ -73,7 +82,7 @@ oc apply -f https://raw.githubusercontent.com/openshift-telco/blueprints-nephio- This will take care of applying the [common dependencies](/content/en/docs/guides/install-guides/common-dependencies.md) and the [common components](/content/en/docs/guides/install-guides/common-components.md) -### Access the Nephio +### Access the Nephio WebUI - Get the Nephio URL: ```bash From 322c700867e2fd839e79ef820bd7bb5d2fed2d05 Mon Sep 17 00:00:00 2001 From: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Date: Fri, 4 Oct 2024 12:23:35 +0100 Subject: [PATCH 30/74] Update location of tutorial files in Porch repo (#174) When the tutorial documentation was moved to the "docs" repo, we did not move the example config into the examples directory in the Porch repo. This PR updates the tutorial to refer to the location of the tutorial files. See also the porch update in this PR: https://github.com/nephio-project/porch/pull/117 --- content/en/docs/porch/using-porch/install-and-using-porch.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index ca23fd1b..3c96742f 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -33,7 +33,7 @@ The following software should be installed prior to running through the tutorial ```bash git clone https://github.com/nephio-project/porch.git -cd porch/docs/tutorials/starting-with-porch/ +cd porch/examples/tutorials/starting-with-porch/ ``` ## Create the Kind clusters for management and edge1 From 21666bd5f351b08dab9433e13880843dd3729ba4 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sat, 5 Oct 2024 09:59:44 +0300 Subject: [PATCH 31/74] Fixing some of the linting erorrs Signed-off-by: Gergely Csatari --- .vale.ini | 2 ++ .vale/config/vocabularies/Nephio/accept.txt | 5 ++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 7d6d7c00..11b503c5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -15,6 +15,8 @@ Vocab = Nephio [*.md] BasedOnStyles = Vale, proselint, alex +IgnoredScope = iframe + # based on https://github.com/errata-ai/Hugo/blob/main/Hugo/.vale.ini # Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 0e4f8036..34c64017 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -48,4 +48,7 @@ TLS VM VMs VSCode -VSphere \ No newline at end of file +VSphere + +# Nephio contributors mentioned in the docs +Tal Liron \ No newline at end of file From 8199a5b751b14320a7edcd784998dfb88e38fb85 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sat, 5 Oct 2024 11:57:36 +0300 Subject: [PATCH 32/74] Additional fixes Signed-off-by: Gergely Csatari --- .vale/config/vocabularies/Nephio/accept.txt | 17 +++++++++++++++-- content/en/docs/architecture.md | 2 +- .../install-guides/common-dependencies.md | 4 ++-- .../install-guides/demo-vagrant-windows.md | 6 +++--- content/en/docs/guides/install-guides/webui.md | 14 +++++++------- content/en/docs/release-notes/R1.md | 4 ++-- content/en/docs/release-notes/R2.md | 8 ++++---- content/en/docs/release-notes/R3.md | 16 ++++++++-------- 8 files changed, 42 insertions(+), 29 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 34c64017..92a8597d 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -1,4 +1,5 @@ # Accepted words (other acronyms must be explained) +Ansible API APIs apiserver @@ -7,6 +8,7 @@ ASNs [Aa]utoscaling cabundle [Cc]onfigmap +[Cc]loudified CLI CRD CRDs @@ -17,6 +19,7 @@ Gitea GitHub GitLab Graphviz +[Hh]ostname [Hh]omebrew [Kk]pt [Kk]ptfile @@ -30,8 +33,14 @@ NFDeployment NFs [Mm]akefile Multus +[Mm]ultivendor +[Mm]ulticloud +OAuth OCI [Oo]nboarding +[Oo]nboarded +Okta +[Pp]arameterization parameterRef passwordless [Pp]kgserver @@ -44,11 +53,15 @@ sudo TLS [Tt]riage [Tt]ko +[Tt]oolchain [Uu]ntar +VirtualBox VM VMs -VSCode -VSphere +VS Code +vSphere +WebUI +xApps # Nephio contributors mentioned in the docs Tal Liron \ No newline at end of file diff --git a/content/en/docs/architecture.md b/content/en/docs/architecture.md index 9c263df9..034e3dff 100644 --- a/content/en/docs/architecture.md +++ b/content/en/docs/architecture.md @@ -21,7 +21,7 @@ The system context view gives a high level perspective of the Nephio software sy ![System Landscape](/static/images/architecture/level2-nephio-container.png) -Nephio is an amalgamation of software systems, so a system landscape provides a high-level view of how those software systems interoperate. +Nephio is an amalgamation of software systems, so a system landscape provides a high-level view of how those software systems operate together. ## Component Views diff --git a/content/en/docs/guides/install-guides/common-dependencies.md b/content/en/docs/guides/install-guides/common-dependencies.md index 851a9823..8e2b0792 100644 --- a/content/en/docs/guides/install-guides/common-dependencies.md +++ b/content/en/docs/guides/install-guides/common-dependencies.md @@ -12,7 +12,7 @@ installation, the CRDs that come along with them are necessary. {{% alert title="Note" color="primary" %}} -If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repo, then replace the `@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. +If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repository, then replace the `@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a git repository. By default it pulls the tag. In case, you have branch with the same name as a tag then to: @@ -51,7 +51,7 @@ kpt live apply resource-backend --reconcile-timeout=15m --output=table ## Setup a Downstream Git Repository Nephio needs a git repository (as a source of truth) to store the packages -which are getting deployed or are already deployed on the cluster. Either you can use Github/Gitlab or Gitea. If you want to use [Gitea](https://about.gitea.com/), +which are getting deployed or are already deployed on the cluster. Either you can use GitHub, GitLab or Gitea. If you want to use [Gitea](https://about.gitea.com/), then you can follow below steps: ```bash diff --git a/content/en/docs/guides/install-guides/demo-vagrant-windows.md b/content/en/docs/guides/install-guides/demo-vagrant-windows.md index 87cc3e6b..e3716287 100644 --- a/content/en/docs/guides/install-guides/demo-vagrant-windows.md +++ b/content/en/docs/guides/install-guides/demo-vagrant-windows.md @@ -6,14 +6,14 @@ weight: 6 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} ## Steps - Install git -- Install virtualbox +- Install VirtualBox - Install [vagrant](https://developer.hashicorp.com/vagrant/docs/installation) - open git bash - `git clone https://github.com/nephio-project/test-infra.git && cd test-infra/e2e/provision` @@ -32,7 +32,7 @@ the Vagrant.configure: `config.vm.network "private_network", ip: "192.168.50.4", virtualbox__intnet: true` -But the easiest way is to force the port-forwarding as shown before: +The easiest way is to force the port-forwarding as shown before: `vagrant ssh -- -L 7007:localhost:7007 -L 3000:172.18.0.200:3000` diff --git a/content/en/docs/guides/install-guides/webui.md b/content/en/docs/guides/install-guides/webui.md index 9c7a8c63..88df8d3b 100644 --- a/content/en/docs/guides/install-guides/webui.md +++ b/content/en/docs/guides/install-guides/webui.md @@ -6,13 +6,13 @@ weight: 6 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not clear. {{% /pageinfo %}} ## Nephio WebUI -To install the WebUI, we simply install a different kpt package. First, we pull the package locally: +To install the WebUI, we install a different kpt package. First, we pull the package locally: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/nephio-packages.git/nephio-webui@origin/v3.0.0 @@ -20,12 +20,12 @@ kpt pkg get --for-deployment https://github.com/nephio-project/nephio-packages.g Before we apply it to the cluster, however, we should configure it. -By default, it expects the webui to be reached via `http://localhost:7007`. If you plan to expose the webui via a load +By default, it expects the WebUI to be reached via `http://localhost:7007`. If you plan to expose the WebUI via a load balancer service instead, then you need to configure the scheme, hostname, port, and service. Note that if you wish to use HTTPS, you should set the `scheme` to `https`, but you will need to terminate the TLS at the load balancer as the container currently only supports HTTP. -This information is captured in the application ConfigMap for the webui, which is generated by a KRM function. We can +This information is captured in the application ConfigMap for the WebUI, which is generated by a KRM function. We can change the values in `nephio-webui/gen-configmap.yaml` just using a text editor (change the `hostname` and `port` values under `params:`), and those will take effect later when we run `kpt fn render`. As an alternative to a text editor, you can run these commands: @@ -43,15 +43,15 @@ or run: kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-kind Service -- 'by-path=spec.type' 'put-value=LoadBalancer' ``` -In the default configuration, the Nephio WebUI *is wide open with no authentication*. The webui itself authenticates to -the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the webui is +In the default configuration, the Nephio WebUI *is wide open with no authentication*. The WebUI itself authenticates to +the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the WebUI is *acting as a cluster admin*. This configuration is designed for *testing and development only*. You must not use this configuration in any other situation, and even for testing and development it must not be exposed on the internet (for example, via a LoadBalancer service). -Configuring authentication for the WebUI is very specific to the particular cluster environment. Guides for different +Configuring authentication for the WebUI is specific to the particular cluster environment. Guides for different environments are below: - [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) diff --git a/content/en/docs/release-notes/R1.md b/content/en/docs/release-notes/R1.md index d98e9bbe..a9d84f43 100644 --- a/content/en/docs/release-notes/R1.md +++ b/content/en/docs/release-notes/R1.md @@ -65,8 +65,8 @@ The following limitations need to be borne in mind: * For infrastructure automation, only the creation of KIND clusters is supported. -* Intercluster networking is not dynamic. Therefore, as more clusters are - deployed, some manual tweaking will be needed for intercluster communications. +* Inter cluster networking is not dynamic. Therefore, as more clusters are + deployed, some manual tweaking will be needed for inter cluster communications. * Provisioning of VLAN interfaces on nodes is currently performed manually. * Feedback of workload deployments from workload clusters to the management cluster is limited. You may need to connect directly to the workload cluster diff --git a/content/en/docs/release-notes/R2.md b/content/en/docs/release-notes/R2.md index 2821f9ac..894453ab 100644 --- a/content/en/docs/release-notes/R2.md +++ b/content/en/docs/release-notes/R2.md @@ -52,7 +52,7 @@ The following functionalities are supported: * API changes * Generalization * Parameterization - * Reuse of params + * Reuse of parameters * Multicloud support * Sandbox * GCP @@ -65,7 +65,7 @@ The following functionalities are supported: * Porch is now part of Nephio and is hosted in the Nephio repository. * Stability. * Security. - * Repo watcher changes. + * Repository watcher changes. * Documentation * New web-based documentation. * Experimental @@ -129,11 +129,11 @@ The following limitations need to be borne in mind: does not match src line`. If such a message appears, then retry in a little while, as this error may resolve itself. Restarting Porch may also help. -* During specialization, we may have duplicate parameterRef extensions, leading to failed deployments +* During specialization, we may have duplicate parameterRef extensions, leading to unsuccesfull deployments (the wrong configurations are generated). The current workaround is to redeploy the package. The bug is due to the NFDeploy reconciliation not being idempotent. * The free5GC operator may create duplicate entries in the SMF function configuration. This will not do any harm, but is nevertheless incorrect. -* Links in the documentation may not render in Github, due to the limitations of the tool being used for +* Links in the documentation may not render in GitHub, due to the limitations of the tool being used for web-based documentation. diff --git a/content/en/docs/release-notes/R3.md b/content/en/docs/release-notes/R3.md index 25027f62..16cdf30d 100644 --- a/content/en/docs/release-notes/R3.md +++ b/content/en/docs/release-notes/R3.md @@ -45,11 +45,11 @@ UI received dependency refresh, new Tabs component and security vulnerabilities * Fixes, Security patches and enhancements to Porch. See [Appendix](#appendix) for details. * The Porch development environment is much improved, with a tutorial, script support, and makefile targets available. Developers can now * Run Porch locally on Kind - * Run the Porch Server or Porch controllers in vscode towards a local Kind porch installation + * Run the Porch Server or Porch controllers in VS Code towards a local Kind porch installation * Run the end to end tests locally * Work on Linux or MacOS locally or using a VM * The Porch documentation was improved with the addition of a Porch tutorial, which steps the user through the main Porch use cases. Documentation on how to use Porchctl was also added - * The Porch build and test toolchain was heavily augmented. Among them was stepping the Go version to 1.22, adding Github actions to build the latest Porch and Porchctl images, support for running the Porch/Porchctl tests locally, and stepping the versions of various dependencies. + * The Porch build and test toolchain was heavily augmented. Among them was stepping the Go version to 1.22, adding GitHub actions to build the latest Porch and Porchctl images, support for running the Porch/Porchctl tests locally, and stepping the versions of various dependencies. * Documentation * Improvements in aesthetics and bug fixes @@ -61,7 +61,7 @@ UI received dependency refresh, new Tabs component and security vulnerabilities * Nephio experimental * [Ytt-declarative-configuration](https://github.com/nephio-experimental/ytt-declarative-configuration) added. This is a generic KPT Function that utilizes the power YTT to achieve higher-level intent automation, reducing complexities and costs associated with infrastructure provisioning. This simplifies deployment and management for the operator by enabling YTT’s templating capabilities to configure network functions. - * [Tko](https://github.com/nephio-experimental/tko) is a self-contained playground for new ideas for Nephio’s future. It stores all data in a traditional SQL backend by default (including support for planetary-scale databases, such as Spanner), validates all KRM before allowing it to be stored in the backend, implements a minimalistic plugin system (included is an SDK for Python-based plugins as well as support for kpt functions), includes a topology plugin (with support for TOSCA) as well as native Helm support, and implements a more declarative specialization workflow. Also includes web and terminal UIs (TUI). + * [Tko](https://github.com/nephio-experimental/tko) is a self-contained playground for new ideas for Nephio’s future. It stores all data in a traditional SQL backend by default (including support for planetary-scale databases, such as Spanner), validates all KRM before allowing it to be stored in the backend, implements a minimalistic plugin system (included is an SDK for Python-based plugins as well as support for kpt functions), includes a topology plugin (with support for TOSCA) as well as native Helm support, and implements a more declarative specialization workflow. Also includes web and terminal user interfaces (UIs) (TUI). * Security * OpenSSF best practices score improved from 3.6 to 7.6 @@ -114,7 +114,7 @@ UI received dependency refresh, new Tabs component and security vulnerabilities * Using the default exponential back-off in case of errors instead of a constant 30 sec retry, see https://github.com/nephio-project/porch/pull/76 * Showing kpt package rendering errors via the status of PackageVariant, see https://github.com/nephio-project/porch/pull/75 * Support for new field selectors: spec.workspaceName and spec.lifecycle on PackageRevision resources, see https://github.com/nephio-project/porch/pull/70 - * Caching in the case of multiple Repository resources pointing to the same git repo is fixed, see https://github.com/nephio-project/porch/pull/68 + * Caching in the case of multiple Repository resources pointing to the same git repository is fixed, see https://github.com/nephio-project/porch/pull/68 * The PackageRevision's metadata.uid field is now unique, see https://github.com/nephio-project/porch/pull/61 * Caching for packageRevisionResources is removed, they should not have been cached, see https://github.com/nephio-project/porch/pull/55 * Pod templating for function runner is introduced, see https://github.com/nephio-project/porch/pull/54 @@ -125,10 +125,10 @@ UI received dependency refresh, new Tabs component and security vulnerabilities * Better unit testing for rpkg commands, see https://github.com/nephio-project/porch/pull/33 * Porchctl rpkg commands now print to stdout on normal completion and stderr on errors, see https://github.com/nephio-project/porch/pull/30 * Porch Security Improvements - * TSupport for cabundle tls for git repo comms, see https://github.com/nephio-project/porch/pull/58 - * TConfiguration of an external webhook and associated certs for resource deletion is now supported https://github.com/nephio-project/porch/pull/53 - * TMissing repository RBAC roles for porch controllers were added, see https://github.com/nephio-project/porch/pull/56 - * TThe porch namespace in the generated cert/webhook can now be configured https://github.com/nephio-project/porch/pull/26 + * Support for CA bundle TLS for git reporepository communications, see https://github.com/nephio-project/porch/pull/58 + * Configuration of an external webhook and associated certs for resource deletion is now supported https://github.com/nephio-project/porch/pull/53 + * Missing repository RBAC roles for porch controllers were added, see https://github.com/nephio-project/porch/pull/56 + * The porch namespace in the generated cert/webhook can now be configured https://github.com/nephio-project/porch/pull/26 From b78a1992b0406fb95669f3ffe310437ac545fbc1 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sat, 5 Oct 2024 19:22:34 +0300 Subject: [PATCH 33/74] Add a note about minumum Go version (#168) Signed-off-by: Gergely Csatari Signed-off-by: Schweier Dominika Signed-off-by: Dominika Schweier Signed-off-by: Michael Greaves Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Co-authored-by: Schweier Dominika Co-authored-by: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Co-authored-by: Rado Chmiel Co-authored-by: Daniel Kostecki <84861140+dkosteck@users.noreply.github.com> --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index 8d59d017..5b7978c2 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,15 @@ In R2 release, a Hugo / Docsy based documentation site was introduced for the Ne ### Setting up the environment +1. The site is using Hugo as the documentation generating engine and as Hugo depends on Go in mudule handling you need to + have Go installed on your computer. Most Linux distributions have Go preinstalled, but some of them have a verstion that is too old +for Hugo. You should have at least version 1.18.0. You can install version 1.18 of go on an Ubuntu using the + following commands: + + 1. `sudo add-apt-repository ppa:longsleep/golang-backports` + 1. `sudo apt update` + 1. `sudo apt install golang-1.18` + 1. The site is using Hugo as the documentation generating engine, therefore you need to install Hugo. As the Docsy template that we use requires transforming Sass to CSS, you will need to install the *extended* version of Hugo. Link to installation instructions is [here](https://gohugo.io/installation/linux/). To ensure that you have the From 6f48a3716573bc19798591f8c2f014b372ab7d43 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sat, 5 Oct 2024 21:07:28 +0300 Subject: [PATCH 34/74] Hopefully correctly ignoring iframes Signed-off-by: Gergely Csatari --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 11b503c5..504729f8 100644 --- a/.vale.ini +++ b/.vale.ini @@ -15,7 +15,7 @@ Vocab = Nephio [*.md] BasedOnStyles = Vale, proselint, alex -IgnoredScope = iframe +SkippedScopes = iframe # based on https://github.com/errata-ai/Hugo/blob/main/Hugo/.vale.ini # Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) From 39469ec9d26ec6f583fcfdc18559debd2583ce75 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sun, 6 Oct 2024 13:33:42 +0300 Subject: [PATCH 35/74] Changing reporter and error level Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index d8500118..6d27e608 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -13,19 +13,19 @@ jobs: - name: Checkout uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - - name: Harden Runner uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1 with: egress-policy: audit - - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog + level: info env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.VALE_GITHUB_TOKEN }} with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check + # more info on these: https://github.com/reviewdog/reviewdog#reporters reporter: github-pr-check token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file From 2aa783cc72ffe78803173cd538fd5de01f7847cf Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Sun, 6 Oct 2024 14:01:09 +0300 Subject: [PATCH 36/74] Maybe fixing the workflow file Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 6d27e608..3c2845cb 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -20,7 +20,6 @@ jobs: - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog - level: info env: REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.VALE_GITHUB_TOKEN }} with: From 526fc881173cc1b73e83bbe9570d03c92f8108ad Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 22 Oct 2024 13:47:19 +0300 Subject: [PATCH 37/74] Correcting Vale errors Signed-off-by: Gergely Csatari --- .vale/config/vocabularies/Nephio/accept.txt | 5 +++++ .../docs/guides/install-guides/install-on-single-vm.md | 9 +++++---- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 92a8597d..e69139ad 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -18,13 +18,17 @@ gcloud Gitea GitHub GitLab +GitOps Graphviz [Hh]ostname [Hh]omebrew [Kk]pt [Kk]ptfile +kubeadm kubectl +kubelet Kubernetes +Libvirt [Nn]amespace Nephio NF @@ -55,6 +59,7 @@ TLS [Tt]ko [Tt]oolchain [Uu]ntar +vCPU VirtualBox VM VMs diff --git a/content/en/docs/guides/install-guides/install-on-single-vm.md b/content/en/docs/guides/install-guides/install-on-single-vm.md index 6d896153..cb3ea904 100644 --- a/content/en/docs/guides/install-guides/install-on-single-vm.md +++ b/content/en/docs/guides/install-guides/install-on-single-vm.md @@ -6,7 +6,7 @@ weight: 4 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} In this guide, you will set up Nephio running in a single VM with: @@ -14,7 +14,7 @@ In this guide, you will set up Nephio running in a single VM with: - **Management Cluster**: [kind](https://kind.sigs.k8s.io/) - **Cluster Provisioner**: [Cluster API](https://cluster-api.sigs.k8s.io/) - **Workload Clusters**: kind -- **Gitops Tool**: ConfigSync +- **GitOps Tool**: ConfigSync - **Git Provider**: Gitea running in the Nephio management cluster will be the git provider for cluster deployment repositories. Some external repositories will be on GitHub. @@ -104,8 +104,9 @@ kpt live init cluster-capi-infrastructure-docker kpt live apply cluster-capi-infrastructure-docker --reconcile-timeout 15m --output=table ``` -The last step is required for defining cluster, machine and kubeadmin templates for controller and worker docker -machines. These templates define the kubelet args, etcd and coreDNS configuration and image repository as other things. +The last step is required for defining cluster, machine and kubeadm templates for controller and worker docker +machines. These templates define the kubelet arguments, etcd and coreDNS configuration and image repository as other +things. ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi-kind-docker-templates@@origin/v3.0.0 From 350118e42cc4fd19a22de6a64b896b684b7ddf93 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 22 Oct 2024 17:47:11 +0300 Subject: [PATCH 38/74] Installing sphinx for vale Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 3c2845cb..65be2047 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -17,7 +17,9 @@ jobs: uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1 with: egress-policy: audit - + - name: Install prerequisites + run: | + sudo apt-get --allow-releaseinfo-change update -y && sudo apt-get install -y python3-sphinx - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog env: From d50e12fc5e042dd219cb0f5e231339a97d4adb9e Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 22 Oct 2024 17:57:57 +0300 Subject: [PATCH 39/74] Fixing vale.ini Signed-off-by: Gergely Csatari --- .vale.ini | 1 - 1 file changed, 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 504729f8..2ca7c802 100644 --- a/.vale.ini +++ b/.vale.ini @@ -14,7 +14,6 @@ Vocab = Nephio [*.md] BasedOnStyles = Vale, proselint, alex - SkippedScopes = iframe # based on https://github.com/errata-ai/Hugo/blob/main/Hugo/.vale.ini From cfcd772db2cf6843c013c5e71152192c03d3b6b5 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 22 Oct 2024 18:18:34 +0300 Subject: [PATCH 40/74] More fixes Signed-off-by: Gergely Csatari --- .vale.ini | 5 +++-- content/en/docs/release-notes/R2.md | 2 +- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.vale.ini b/.vale.ini index 2ca7c802..7d9cc87f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -11,10 +11,10 @@ MinAlertLevel = suggestion # Configure a dictionary specific to Nephio Vocab = Nephio +SkippedScopes = iframe [*.md] BasedOnStyles = Vale, proselint, alex -SkippedScopes = iframe # based on https://github.com/errata-ai/Hugo/blob/main/Hugo/.vale.ini # Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}}) @@ -25,4 +25,5 @@ TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \ # Exclude `{{< myshortcode `This is some HTML, ... >}}` BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \ -(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) \ No newline at end of file +(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}) + diff --git a/content/en/docs/release-notes/R2.md b/content/en/docs/release-notes/R2.md index 894453ab..7eee0a30 100644 --- a/content/en/docs/release-notes/R2.md +++ b/content/en/docs/release-notes/R2.md @@ -129,7 +129,7 @@ The following limitations need to be borne in mind: does not match src line`. If such a message appears, then retry in a little while, as this error may resolve itself. Restarting Porch may also help. -* During specialization, we may have duplicate parameterRef extensions, leading to unsuccesfull deployments +* During specialization, we may have duplicate parameterRef extensions, leading to failed deployments (the wrong configurations are generated). The current workaround is to redeploy the package. The bug is due to the NFDeploy reconciliation not being idempotent. From dd05842c75df1476eabe90d4d52a9982379a4afe Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Tue, 22 Oct 2024 18:22:30 +0300 Subject: [PATCH 41/74] Trigger for every PR action Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 65be2047..886120d0 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -1,8 +1,6 @@ name: reviewdog on: - pull_request_target: - types: [assigned, opened, edited, ready_for_review] - + pull_request: workflow_dispatch: jobs: From 3766ce2e8b9e69780140c1b518cd4bc4689d8e0d Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Wed, 23 Oct 2024 18:01:56 +0300 Subject: [PATCH 42/74] Changes proposed by Vale Signed-off-by: Gergely Csatari --- .vale/config/vocabularies/Nephio/accept.txt | 12 +- .../en/docs/guides/install-guides/_index.md | 34 +- .../install-guides/common-components.md | 55 +-- .../install-guides/explore-nephio-free5gc.md | 70 +-- .../guides/install-guides/explore-sandbox.md | 28 +- .../guides/install-guides/install-on-byoc.md | 138 +++--- .../install-guides/install-on-multiple-vm.md | 9 +- .../install-guides/install-on-openshift.md | 8 +- .../install-guides/package-transformations.md | 448 ++++++++---------- .../guides/install-guides/webui-auth-gcp.md | 8 +- .../guides/install-guides/webui-auth-okta.md | 22 +- 11 files changed, 391 insertions(+), 441 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index e69139ad..735db924 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -1,5 +1,6 @@ # Accepted words (other acronyms must be explained) Ansible +Anthos API APIs apiserver @@ -12,7 +13,9 @@ cabundle CLI CRD CRDs +Crossplane Dockerfile +envtest [Ee]tcd gcloud Gitea @@ -28,6 +31,7 @@ kubeadm kubectl kubelet Kubernetes +Kustomize Libvirt [Nn]amespace Nephio @@ -50,17 +54,23 @@ passwordless [Pp]kgserver [Pp]orch [Pp]orchctl +Postgres [Rr]pkg +rootsync +starlark stdout stderr -sudo +[Ss]udo TLS [Tt]riage [Tt]ko [Tt]oolchain +URIs [Uu]ntar vCPU VirtualBox +VLAN +VLANs VM VMs VS Code diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md index 872bf863..0c7745cb 100644 --- a/content/en/docs/guides/install-guides/_index.md +++ b/content/en/docs/guides/install-guides/_index.md @@ -6,7 +6,7 @@ weight: 1 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} ## Introduction @@ -100,8 +100,12 @@ sudo NEPHIO_DEBUG=false \ **Pre-installed K8s Cluster** Log onto your VM/System and run the following command: -(NOTE: The VM or System should be able to access the K8S API server via the kubeconfig file and have docker installed. -Docker is needed to run the KRM container functions specified in rootsync and repository packages.) + +{{% alert title="Note" color="primary" %}} +The VM or System should be able to access the K8S API server via the kubeconfig file and have docker installed. +Docker is needed to run the KRM container functions specified in rootsync and repository packages. +{{% /alert %}} + ```bash wget -O - https://raw.githubusercontent.com/nephio-project/test-infra/v3.0.0/e2e/provision/init.sh | \ @@ -116,18 +120,18 @@ sudo NEPHIO_DEBUG=false \ The following environment variables can be used to configure the installation: -| Variable | Values | Default Value | Description | -|------------------------|------------------| -------------------|------------------------------------------------------------------------------| -| NEPHIO_USER | userid | ubuntu | The user to install the sandbox on (must have sudo passwordless permissions) | -| NEPHIO_DEBUG | false or true | false | Controls debug output from the install | -| NEPHIO_HOME | path | /home/$NEPHIO_USER | The directory to check out the install scripts into | -| RUN_E2E | false or true | false | Specifies whether end-to-end tests should be executed or not | -| DOCKERHUB_USERNAME | alpha-num string | | Specifies the dockerhub username | -| DOCKERHUB_TOKEN | alpha-num string | | Specifies the password or token | -| NEPHIO_REPO | URL | https://github.com/nephio-project/test-infra.git | URL of the repository to be used for installation | -| NEPHIO_BRANCH | branch | main/v3.0.0 | Tag or branch name to use in NEPHIO_REPO | -| DOCKER_REGISTRY_MIRRORS | list of URLs in JSON format | | List of docker registry mirrors in JSON format, or empty for no mirrors to be set. Example value: ``["https://docker-registry-remote.mycompany.com", "https://docker-registry-remote2.mycompany.com"]`` | -| K8S_CONTEXT | K8s context | kind-kind | Kubernetes context for existing non-kind cluster (gathered from `kubectl config get-contexts`, for example "kubernetes-admin@kubernetes") | +| Variable | Values | Default Value | Description | +|---------------------------|------------------| -------------------|------------------------------------------------------------------------------| +| *NEPHIO_USER* | userid | ubuntu | The user to install the sandbox on (must have sudo passwordless permissions) | +| *NEPHIO_DEBUG* | false or true | false | Controls debug output from the install | +| *NEPHIO_HOME* | path | /home/$NEPHIO_USER | The directory to check out the install scripts into | +| *RUN_E2E* | false or true | false | Specifies whether end-to-end tests should be ran or not | +| *DOCKERHUB_USERNAME* | alpha-num string | | Specifies the Docker Hub username | +| *DOCKERHUB_TOKEN* | alpha-num string | | Specifies the password or token | +| *NEPHIO_REPO* | URL | https://github.com/nephio-project/test-infra.git | URL of the repository to be used for installation | +| *NEPHIO_BRANCH* | branch | main/v3.0.0 | Tag or branch name to use in NEPHIO_REPO | +| *DOCKER_REGISTRY_MIRRORS* | list of URLs in JSON format | | List of docker registry mirrors in JSON format, or empty for no mirrors to be set. Example value: ``["https://docker-registry-remote.mycompany.com", "https://docker-registry-remote2.mycompany.com"]`` | +| *K8S_CONTEXT* | K8s context | kind-kind | Kubernetes context for existing non-kind cluster (gathered from `kubectl config get-contexts`, for example *kubernetes-admin@kubernetes*) | ### Follow the Installation on VM diff --git a/content/en/docs/guides/install-guides/common-components.md b/content/en/docs/guides/install-guides/common-components.md index 0f739640..4f9c3f4c 100644 --- a/content/en/docs/guides/install-guides/common-components.md +++ b/content/en/docs/guides/install-guides/common-components.md @@ -8,15 +8,18 @@ weight: 2 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} {{% alert title="Note" color="primary" %}} -If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repo, then replace the `@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. +If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repository, then replace the +`@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you +wish to use. -While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a git repository. By default it pulls the tag. In case, you have branch with the same name as a tag then to: +While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a +git repository. By default it pulls the tag. In case, you have branch with the same name as a tag then to: ```bash #pull a branch @@ -29,14 +32,12 @@ kpt pkg get --for-deployment @v3.0.0 ## Porch -This "Package Orchestration" component provides the Kubernetes APIs for -Repositories, PackageRevisions, PackageRevisionResources, PackageVariants, and -PackageVariantSets. Nephio relies on it to inventory, clone, and mutate -packages. It also provides the API layer that shields the Nephio components -from direct interaction with the Git (or OCI) storage layer. +This "Package Orchestration" component provides the Kubernetes APIs for Repositories, PackageRevisions, +PackageRevisionResources, PackageVariants, and PackageVariantSets. Nephio relies on it to inventory, clone, and mutate +packages. It also provides the API layer that shields the Nephio components from direct interaction with the Git +(or OCI) storage layer. -Fetch the package using `kpt`, and run any `kpt` functions, and then apply the -package: +Fetch the package using `kpt`, and run any `kpt` functions, and then apply the package: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog/nephio/core/porch@origin/v3.0.0 @@ -47,12 +48,9 @@ kpt live apply porch --reconcile-timeout=15m --output=table ## Nephio Operators -The Nephio Operators provide implementations of the Nephio-specific APIs. This -includes the code that implements the various package specialization features - -such as integration with IPAM and VLAN allocation, and NAD generation - as well -as operators that can provision repositories and bootstrap new clusters into -Nephio. - +The Nephio Operators provide implementations of the Nephio-specific APIs. This includes the code that implements the +various package specialization features - such as integration with IPAM and VLAN allocation, and NAD generation - as +well as operators that can provision repositories and bootstrap new clusters into Nephio. To install the Nephio Operators, repeat the `kpt` steps, but for that package: @@ -60,9 +58,8 @@ To install the Nephio Operators, repeat the `kpt` steps, but for that package: kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/nephio-operator@origin/v3.0.0 ``` -The Nephio Operator package by default uses the Gitea instance at `172.18.0.200:3000` as -the git repository. Change it to point to your git instance in -`nephio-operator/app/controller/deployment-token-controller.yaml` and +The Nephio Operator package by default uses the Gitea instance at `172.18.0.200:3000` as the git repository. Change it +to point to your git instance in `nephio-operator/app/controller/deployment-token-controller.yaml` and `nephio-operator/app/controller/deployment-controller.yaml` You also need to create a secret with your Git instance credentials: @@ -91,14 +88,12 @@ kpt live apply nephio-operator --reconcile-timeout=15m --output=table ## Management Cluster GitOps Tool -A GitOps tool (ConfigSync) is installed to allow -GitOps-based application of packages on the management cluster itself. It is -not needed if you only want to provision network functions, but it -is used extensively in the cluster provisioning workflows. +A GitOps tool (ConfigSync) is installed to allow GitOps-based application of packages on the management cluster itself. +It is not needed if you only want to provision network functions, but it is used extensively in the cluster provisioning +workflows. -Different GitOps tools may be used, but these instructions only cover ConfigSync. -To install it on the management cluster, we again follow the same process. -Later, we will configure it to point to the `mgmt` repository: +Different GitOps tools may be used, but these instructions only cover ConfigSync. To install it on the management +cluster, we again follow the same process. Later, we will configure it to point to the `mgmt` repository: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@origin/v3.0.0 @@ -109,9 +104,8 @@ kpt live apply configsync --reconcile-timeout=15m --output=table ## Nephio Stock Repositories -The repositories with the Nephio packages used in the exercises are available to -be installed via a package for convenience. This will install repository -resources pointing directly to the GitHub repositories, with read-only access. +The repositories with the Nephio packages used in the exercises are available to be installed via a package for +convenience. This will install repository resources pointing directly to the GitHub repositories, with read-only access. ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/optional/stock-repos@origin/v3.0.0 @@ -122,4 +116,5 @@ kpt live apply stock-repos --reconcile-timeout=15m --output=table ## WebUI (Optional) -Nephio WebUI is optional and to install it you can follow this [document](/content/en/docs/guides/install-guides/webui.md) +Nephio WebUI is optional and to install it you can follow this +[document](/content/en/docs/guides/install-guides/webui.md) diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md index 3ee54086..96890331 100644 --- a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md +++ b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md @@ -11,7 +11,7 @@ Concepts as [Operator](/content/en/docs/glossary.md#operator) and ## Deploy the operator to the cluster -In the [nephio/free5gc repository](https://github.com/nephio-project/free5gc) the **Makefile** is used to +In the [Nephio Free5gc repository](https://github.com/nephio-project/free5gc) the **Makefile** is used to [deploy the operator to the cluster](https://github.com/nephio-project/free5gc/tree/main#getting-started) automating tasks such as @@ -28,62 +28,64 @@ tasks such as * undeploy: Undeploys the controller from the Kubernetes cluster. 3. Build Dependencies: - * Targets for installing and managing build dependencies like kustomize, controller-gen, and envtest. + * Targets for installing and managing build dependencies like Kustomize, controller-gen, and envtest. ## The structure of the repository 1. [Operator](https://github.com/nephio-project/free5gc/tree/main/free5gc-operator) - * Binding metrics and healthcheck ports + * Binding metrics and hcheck ports * Registering UPF SMF AMF deployments * Reconciler and Setup (Creating Controllers) 2. [Controllers](https://github.com/nephio-project/free5gc/tree/main/controllers) - * **Reconciler**: The XXFDeploymentReconciler struct is responsible for reconciling the state of the XXFDeployment + * **Reconciler**: The *XXFDeploymentReconciler* struct is responsible for reconciling the state of the *XXFDeployment* resource in the Kubernetes cluster. It implements the *Reconcile* function, which is called by the Controller Runtime - framework when changes occur to the XXFDeployment resource. The *Reconcile* function performs various operations such - as creating or updating the **ConfigMap** and **Service** resources associated with the XXFDeployment. - Overall, the XXFDeploymentReconciler struct acts as the controller for the XXFDeployment resource, ensuring that the + framework when changes occur to the *XXFDeployment* resource. The *Reconcile* function performs various operations such + as creating or updating the **ConfigMap** and **Service** resources associated with the *XXFDeployment*. + Overall, the *XXFDeploymentReconciler* struct acts as the controller for the *XXFDeployment* resource, ensuring that the cluster state aligns with the desired state specified by the user. * **Resources**: functions that provide the necessary logic to create the required Kubernetes resources for an XXF deployment, including the deployment, service, and configuration map: - * *createDeployment*: This function creates a Deployment resource for the AMF deployment. It defines the desired + * **createDeployment**: This function creates a *Deployment* resource for the AMF deployment. It defines the desired state of the deployment, including the number of replicas, container image, ports, command, arguments, volume mounts, resource requirements, and security context. - * *createService*: This function creates a Service resource for the AMF deployment. It defines the desired state of - the service, including the selector for the associated deployment and the ports it exposes. - * *createConfigMap*: This function creates a ConfigMap resource for the AMF deployment. It generates the - configuration data for the AMF based on the provided template values and renders it into the amfcfg.yaml file. - * *createResourceRequirements*: This function calculates the resource requirements (CPU and memory limits and - requests) for the AMF deployment based on the specified capacity and sets them in a ResourceRequirements object. - * *createNetworkAttachmentDefinitionNetworks*: This function creates the network attachment definition networks for - the AMF deployment. It uses the CreateNetworkAttachmentDefinitionNetworks function from the controllers package to - generate the network attachment definition YAML based on the provided template name and interface configurations. - * **Templates**: The configuration template includes various parameters. Example for AMF: version, description, - ngapIpList, sbi, nrfUri, amfName, serviceNameList, servedGuamiList, supportTaiList, plmnSupportList, supportDnnList, - security settings, networkName, locality, networkFeatureSupport5GS, timers, and logger configurations. - The *renderConfigurationTemplate* function takes a struct (configurationTemplateValues) containing the values for - placeholders in the template and renders the final configuration as a string. The rendered configuration can then be - used by the AMF application. + * **createService**: This function creates a *Service* resource for the AMF deployment. It defines the desired state + of the service, including the selector for the associated deployment and the ports it exposes. + * **createConfigMap**: This function creates a *ConfigMap* resource for the AMF deployment. It generates the + configuration data for the AMF based on the provided template values and renders it into the *amfcfg.yaml* file. + * **createResourceRequirements**: This function calculates the resource requirements (CPU and memory limits and + requests) for the AMF deployment based on the specified capacity and sets them in a *ResourceRequirements* object. + * **createNetworkAttachmentDefinitionNetworks**: This function creates the network attachment definition networks for + the AMF deployment. It uses the *CreateNetworkAttachmentDefinitionNetworks* function from the controllers package + to generate the network attachment definition YAML based on the provided template name and interface + configurations. + * **Templates**: The configuration template includes various parameters. Example for AMF: *version*, *description*, + *ngapIpList*, *sbi*, *nrfUri*, *amfName*, *serviceNameList*, *servedGuamiList*, *supportTaiList*, *plmnSupportList*, + *supportDnnList*, security settings, *networkName*, *locality*,* networkFeatureSupport5GS*, timers, and logger + configurations. The *renderConfigurationTemplate* function takes a struct (*configurationTemplateValues*) containing + the values for placeholders in the template and renders the final configuration as a string. The rendered + configuration can then be used by the AMF application. * **Status**: It holds the logic to get the status of the deployment and displaying it as "Available," "Progressing," and "ReplicaFailure".The function returns the *NFDeploymentStatus* object and a boolean value indicating whether the status has been updated or not. 3. [Config](https://github.com/nephio-project/free5gc/tree/main/config) - There are [Kustomization](https://github.com/kubernetes-sigs/kustomize) file for a Kubernetes application, specifying various configuration options and resources for the application. + There are [Kustomize](https://github.com/kubernetes-sigs/kustomize) files for a Kubernetes application, specifying + various configuration options and resources for the application. In the */default* folder there are: -* *Namespace*: Defines the namespace (free5gc) where all resources will be deployed. -* *Name Prefix*: Specifies a prefix (free5gc-operator-) that will be prepended to the names of all resources. -* *Common Labels*: Allows adding labels to all resources and selectors. Currently commented out. -* *Bases*: Specifies the directories (../crd, ../rbac, ../operator) containing the base resources for the application. - In the *crd/base* folder there are CRDs for the workload network functions. They define the schema for the - "XXFDeployment" resource under the "workload.nephio.org" group. Also, there are YAML config files for teaching - kustomize how to substitute *name* and *namespace* reference in CRD. -* *Patches Strategic Merge*: Specifies the patches that should be applied to the base resources. +* **Namespace**: Defines the namespace (free5gc) where all resources will be deployed. +* **Name Prefix**: Specifies a prefix (free5gc-operator-) that will be prefixed to the names of all resources. +* **Common Labels**: Allows adding labels to all resources and selectors. Currently commented out. +* **Bases**: Specifies the directories (*../crd*, *../rbac*, *../operator*) containing the base resources for the + application. In the *crd/base* folder there are CRDs for the workload network functions. They define the schema for + the *XXFDeployment* resource under the *workload.nephio.org* group. Also, there are YAML config files for teaching + Kustomize how to substitute *name* and *namespace* reference in CRD. +* **Patches Strategic Merge**: Specifies the patches that should be applied to the base resources. Currently includes a patch file named *manager_auth_proxy_patch.yaml*, which adds authentication protection to the - /metrics endpoint. -* *Vars*: Defines variables that can be used for variable substitution. + */metrics* endpoint. +* **Vars**: Defines variables that can be used for variable substitution. diff --git a/content/en/docs/guides/install-guides/explore-sandbox.md b/content/en/docs/guides/install-guides/explore-sandbox.md index 2bd89bdf..4ad95e11 100644 --- a/content/en/docs/guides/install-guides/explore-sandbox.md +++ b/content/en/docs/guides/install-guides/explore-sandbox.md @@ -104,15 +104,15 @@ The following base components are installed on the Management cluster. Base comp that are needed for the Nephio sandbox, which Nephio uses out of the box. In real world installations, alternative components that provide the same functionality may be used. -| Component | Purpose | -| ------------ | -------------------------------------------------------------------| -| Metal LB | Used to load balances requests to the cluster | -| Cert Manager | Used for certificate management | -| Gitea | Used to allow creation and management of local git repos by Nephio | -| Postgres | Used by Gitea to store repositories | -| Cluster API | Used to deploy Workload clusters | -| IPAM | A reference backend system to allocate and manage IP addresses | -| VLAN | A reference backend system used to allocate and manage VLANs | +| Component | Purpose | +| ------------ | --------------------------------------------------------------------------| +| Metal LB | Used to load balances requests to the cluster | +| Cert Manager | Used for certificate management | +| Gitea | Used to allow creation and management of local git repositories by Nephio | +| Postgres | Used by Gitea to store repositories | +| Cluster API | Used to deploy Workload clusters | +| IPAM | A reference backend system to allocate and manage IP addresses | +| VLAN | A reference backend system used to allocate and manage VLANs | ### Specific Components @@ -120,16 +120,16 @@ The following specific components are installed on the Management cluster. The s and components from [Google Container Tools](https://github.com/GoogleContainerTools) that Nephio uses heavily and interacts closely with. -| Component | Purpose | -| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Porch | Google Container Tools Package Orchestration Server, provides an API used by Nephio to work with packages in git repos | -| ConfigSync | Google Container Tools Configuration Synchronization, used by Nephio to deploy configurations from repos from the Management cluster onto Workload clusters | +| Component | Purpose | +| ------------------ | ------------------------------------------------------------------------------------------------| +| Porch | Google Container Tools Package Orchestration Server, provides an API used by Nephio to work with packages in git repositries | +| ConfigSync | Google Container Tools Configuration Synchronization, used by Nephio to deploy configurations from repositories from the Management cluster onto Workload clusters | | Nephio Controllers | The Nephio controllers, which implement the Nephio functionality to fetch, manipulate, and deploy NFs | | Nephio WebUI | The Nephio web client | ## Some Useful Commands -Easily get the kubeconfig for a CAPI KinD cluster: +Get the kubeconfig for a CAPI KinD cluster: ```bash get_capi_kubeconfig regional diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 3df9a50b..cedad828 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -7,73 +7,70 @@ weight: 3 ## Introduction -There are many ways to assemble a Nephio installation. This Installation Guide -describes the common pieces across environments, and describes the choices that -need to be made to create a "Bring Your Own Cluster" Nephio installation. -Because there are so many combinations, a comprehensive guide is not practical. -Instead, several guides showing opinionated installations are available. +There are many ways to assemble a Nephio installation. This Installation Guide describes the common pieces across +environments, and describes the choices that need to be made to create a "Bring Your Own Cluster" Nephio installation. +Because there are so many combinations, a comprehensive guide is not practical. Instead, several guides showing +opinionated installations are available. ## Prerequisites -Regardless of the specific choices you make, you will need the following -prerequisites. This is in addition to any prerequisites that are specific to -your environment and choices. - - a Linux workstation with internet access - - `kubectl` [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation - - `kpt` [installed](https://kpt.dev/installation/kpt-cli) on your workstation - (version v1.0.0-beta.43 or later) - - `porchctl` [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation - - Sudo-less `docker`, `podman`, or `nerdctl`. If using `podman` or `nerdctl`, - you must set the -[`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) -environment variable. - -As part of all installations, you will create or utilize an existing Kubernetes -management cluster. The management cluster must have internet access, and must -be a non-EOL Kubernetes version. Additionally: - - Your default `kubectl` context should point to the cluster - - You will need cluster administrator privileges (in particular you will need - to be able to create namespaces and other cluster-scoped resources). - -You will use `kpt` for most of the installation packages in these instructions, -though you could also use `kubectl` directly to apply the resources, once they -are configured. - -After installing the prerequisites, create a local directory on your -workstation to hold the local package instances for installing the various -components: +Regardless of the specific choices you make, you will need the following prerequisites. This is in addition to any +prerequisites that are specific to your environment and choices. + +- a Linux workstation with internet access +- `kubectl` [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation +- `kpt` [installed](https://kpt.dev/installation/kpt-cli) on your workstation + (version v1.0.0-beta.43 or later) +- `porchctl` [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation +- Sudo-less `docker`, `podman`, or `nerdctl`. If using `podman` or `nerdctl`, + you must set the [`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) environment + variable. + +As part of all installations, you will create or utilize an existing Kubernetes management cluster. The management +cluster must have internet access, and must be a non-EOL Kubernetes version. Additionally: + +- Your default `kubectl` context should point to the cluster +- You will need cluster administrator privileges (in particular you will need to be able to create namespaces and other + cluster-scoped resources). + +You will use `kpt` for most of the installation packages in these instructions, though you could also use `kubectl` +directly to apply the resources, once they are configured. + +After installing the prerequisites, create a local directory on your workstation to hold the local package instances for +installing the various components: ```bash mkdir nephio-install cd nephio-install ``` -The instructions for setting up the opinionated installations will assume you -have installed the prerequisites and created the `nephio-install` directory. +The instructions for setting up the opinionated installations will assume you have installed the prerequisites and +created the `nephio-install` directory. ## Opinionated Installations -Instructions are provided for several different opinionated installations in -the table below. Following this section are descriptions of the various -options, if you wish to assemble your own set of components. +Instructions are provided for several different opinionated installations in the table below. Following this section are +descriptions of the various options, if you wish to assemble your own set of components. | Environment | Description | | ----------- | ---------------------------------------------------------- | | [Single VM](/content/en/docs/guides/install-guides/install-on-single-vm.md) | The single VM demo environment, set up "the hard way" - without using the included provisioning script. This creates a complete Nephio-in-a-VM, just like the R1 demo environment. These instructions cover both Ubuntu and Fedora. | | [Multiple VM](/content/en/docs/guides/install-guides/install-on-multiple-vm.md) | The multiple VM environment, set up Nephio on multiple VMs. These instructions cover both Ubuntu and Fedora. | -| [Google Cloud Platform](/content/en/docs/guides/install-guides/install-on-gcp.md) | Nephio running in GCP. A GKE cluster is used as the management cluster, with Anthos Config Controller for GCP infrastructure provisioning, Gitea as the Git provider, and Web UI authentication and authorization via Google OAuth 2.0 | -| [OpenShift](/content/en/docs/guides/install-guides/install-on-openshift.md) | Nephio running in OpenShift, with Cluster API as the cluster provisioner, Gitea as the Git provider and Web UI authentication backed by Open Shift OIDC. | +| [Google Cloud Platform](/content/en/docs/guides/install-guides/install-on-gcp.md) | Nephio running in GCP. A GKE cluster is used as the management cluster, with Anthos Config Controller for GCP infrastructure provisioning, Gitea as the Git provider, and WebUI authentication and authorization via Google OAuth 2.0 | +| [OpenShift](/content/en/docs/guides/install-guides/install-on-openshift.md) | Nephio running in OpenShift, with Cluster API as the cluster provisioner, Gitea as the Git provider and WebUI authentication backed by OpenShift OIDC. | -## A La Carte Installation +## À La Carte Installation -If you wish to create a completely "a la carte" installation rather than using -a documented opinionated environment, this section will help you understand the -choices you need to make among various dependencies and components. +If you wish to create a completely "à la carte" installation rather than using a documented opinionated environment, +this section will help you understand the choices you need to make among various dependencies and components. ### Git Providers -Nephio can support multiple Git providers for the repositories that contain -packages. In R1, R2 and R3 only Gitea repositories can be provisioned directly by Nephio; other Git providers will require manual provisioning of new repositories. But most Git providers can be supported (via standard Git protocols) as repositories for packages for read and write. It is also perfectly fine to use multiple providers; in the R1 demo environment, GitHub is used for upstream external repositories while Gitea is used for the workload cluster repositories. +Nephio can support multiple Git providers for the repositories that contain packages. In R1, R2 and R3 only Gitea +repositories can be provisioned directly by Nephio; other Git providers will require manual provisioning of new +repositories. But most Git providers can be supported (via standard Git protocols) as repositories for packages for read +and write. It is also perfectly fine to use multiple providers; in the R1 demo environment, GitHub is used for upstream +external repositories while Gitea is used for the workload cluster repositories. A non-exhaustive list of options: @@ -84,22 +81,21 @@ A non-exhaustive list of options: | [GitLab](https://about.gitlab.com/) | Yes | No | | [Google CSR](https://cloud.google.com/source-repositories/docs) | Yes | Yes, with KCC | -See the [Porch user -guide](https://kpt.dev/guides/porch-user-guide?id=repository-registration) to -see how to register repositories in Nephio. +See the [Porch user guide](https://kpt.dev/guides/porch-user-guide?id=repository-registration) to see how to register +repositories in Nephio. -In R1, we must install Gitea, even if you are using another provider. However, -there are slight differences per environment, so that installation will be -documented in the specific environment instructions. +In R1, we must install Gitea, even if you are using another provider. However, there are slight differences per +environment, so that installation will be documented in the specific environment instructions. ### GitOps Tool -As configured in the R1, R2 and R3 reference implementation, Nephio relies on ConfigSync. However, it is possible to configure it to use a different GitOps tool, such as Flux or ArgoCD to apply packages to the clusters. +As configured in the R1, R2 and R3 reference implementation, Nephio relies on ConfigSync. However, it is possible to +configure it to use a different GitOps tool, such as Flux or ArgoCD to apply packages to the clusters. ### Cluster Provisioner -R1 uses Cluster API, but other options may be used such as Crossplane, Google -KCC, or AWS Controllers for Kubernetes. You can provision more than one. +R1 uses Cluster API, but other options may be used such as Crossplane, Google KCC, or AWS Controllers for Kubernetes. +You can provision more than one. | Provider | Notes | | ----------- | --------------------------------------------------------------------------------------- | @@ -109,36 +105,34 @@ KCC, or AWS Controllers for Kubernetes. You can provision more than one. ### Load Balancer -The R1, R2 amd R3 demo environments use [MetalLB](https://metallb.universe.tf/), but if you are running in a cloud, you probably do not need anything special here. However, depending on your choice of GitOps tool and Git provider, some of the packages may need customization to provision or use a well-known load balancer IP or DNS name. +The R1, R2 and R3 demo environments use [MetalLB](https://metallb.universe.tf/), but if you are running in a cloud, you +probably do not need anything special here. However, depending on your choice of GitOps tool and Git provider, some of +the packages may need customization to provision or use a well-known load balancer IP or DNS name. ### Gateway or Ingress -If you wish to avoid running `kubectl port-forward`, the use of Kubernetes -Ingress or Gateway is recommended. +If you wish to avoid running `kubectl port-forward`, the use of Kubernetes Ingress or Gateway is recommended. ### Nephio WebUI Authentication and Authorization -In the default configuration, the Nephio WebUI *is wide open with no -authentication*. The webui itself authenticates to the cluster using a static -service account, which is bound to the cluster admin role. Any user accessing -the webui is *acting as a cluster admin*. +In the default configuration, the Nephio WebUI *is wide open with no authentication*. The WebUI itself authenticates to +the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the WebUI is +*acting as a cluster admin*. -This configuration is designed for *testing and development only*. You must not -use this configuration in any other situation, and even for testing and -development it must not be exposed on the internet (for example, via a -LoadBalancer service, Ingress, or Route). +This configuration is designed for *testing and development only*. You must not use this configuration in any other +situation, and even for testing and development it must not be exposed on the internet (for example, via a LoadBalancer +service, Ingress, or Route). The WebUI currently supports the following options: + - [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) - [OIDC with Okta](/content/en/docs/guides/install-guides/webui-auth-okta.md) ### Nephio Stock Repositories -It is recommended that you create a repository specific to your installation -environment. The packages in this repository can be derivatives of the various -Nephio packages that are part of the demonstration environment. This allows -exiting PackageVariant and PackageVariantSet resources to work as expected, -simply by changing the Git repository pointed to by the Repository resource. +It is recommended that you create a repository specific to your installation environment. The packages in this +repository can be derivatives of the various Nephio packages that are part of the demonstration environment. This allows +exiting PackageVariant and PackageVariantSet resources to work as expected, simply by changing the Git repository +pointed to by the Repository resource. -You may want to create a package containing those Repository resources, much as -is done for the sandbox environment. +You may want to create a package containing those Repository resources, much as is done for the sandbox environment. diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index b43f7b6d..98051cfb 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -6,7 +6,8 @@ weight: 7 --- ## Prerequisites -* Cluster Management (master) + +* Cluster Management (controller) * 4 vCPU * 8 GB RAM * Kubernetes version 1.26+ @@ -46,14 +47,14 @@ kpt live apply configsync --reconcile-timeout=15m --output=table ### Create Git Repository -Create a repository for your cluster either in your git provider or in gitea. +Create a repository for your cluster either in your git provider or in Gitea. If you want to use GitHub or GitLab then follow below steps Get a [GitHub token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) if your repository is private, to allow Porch to make modifications. -Register the edge repository using kpt cli or nephio web-ui. +Register the edge repository using kpt CLI or Nephio WebUI. ```bash GITHUB_USERNAME= @@ -81,7 +82,7 @@ kpt live apply --reconcile-timeout=15m --output=table {{% alert title="Note" color="primary" %}} * For management cluster you have to name the repository as `mgmt`. -* In the `repository` package by default gitea address is `172.18.0.200:3000` in `repository/set-values.yaml` +* In the `repository` package by default Gitea address is `172.18.0.200:3000` in `repository/set-values.yaml` change this to your git address. * `repository/token-configsync.yaml` and `repository/token-porch.yaml` are responsible for creating secrets with the help of Nephio token controller for accessing git instance for root-sync. You would need the name of config-sync token to provide it to root-sync. diff --git a/content/en/docs/guides/install-guides/install-on-openshift.md b/content/en/docs/guides/install-guides/install-on-openshift.md index a1015e2b..79943923 100644 --- a/content/en/docs/guides/install-guides/install-on-openshift.md +++ b/content/en/docs/guides/install-guides/install-on-openshift.md @@ -6,7 +6,7 @@ weight: 3 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} @@ -15,17 +15,17 @@ In this guide, you will set up Nephio with: - **Management Cluster**: OpenShift with [Advanced Cluster Management](https://www.redhat.com/en/technologies/management/advanced-cluster-management) - **Cluster Provisioner**: Assisted Service - **Workload Clusters**: OpenShift Cluster or Single Node OpenShift Cluster or HyperShift Cluster or Remote Worker Node -- **Gitops Tool**: [OpenShift GitOps](https://www.redhat.com/en/technologies/cloud-computing/openshift/gitops) backed by +- **GitOps Tool**: [OpenShift GitOps](https://www.redhat.com/en/technologies/cloud-computing/openshift/gitops) backed by ArgoCD - **Git Provider**: Gitea running in the Nephio management cluster will be the git provider for cluster deployment repositories. Some external repositories will be on GitHub. - **Web UI Auth**: OpenShift OAuth. -- **Ingress/Load Balancer**: OpenShift Ingress will be used, supplying a Route to the Nephio and Gitea Web UIs. +- **Ingress/Load Balancer**: OpenShift Ingress will be used, supplying a Route to the Nephio and Gitea WebUIs. ## Prerequisites - A Red Hat Account and access to https://console.redhat.com/openshift/ -- OpenShift cli client `oc`. [Download here](https://console.redhat.com/openshift/downloads) +- OpenShift CLI client `oc`. [Download here](https://console.redhat.com/openshift/downloads) ## Setup the Management Cluster diff --git a/content/en/docs/guides/install-guides/package-transformations.md b/content/en/docs/guides/install-guides/package-transformations.md index 8819cc45..05106265 100644 --- a/content/en/docs/guides/install-guides/package-transformations.md +++ b/content/en/docs/guides/install-guides/package-transformations.md @@ -7,31 +7,28 @@ weight: 7 ## Vanilla kpt for the Management cluster -Before reading this, please read [the kpt book](https://kpt.dev/book/). +Before reading this, please read [The kpt book](https://kpt.dev/book/). ### kpt pkg get -The `kpt pkg get --for-deployment -https:///@/ -` command downloads a kpt package from a repository. +The `kpt pkg get --for-deployment https:///@/ ` +command downloads a kpt package from a repository. The fields in the command above are as follows: | Field | Description | | ---------------- | -------------------------------------------------------------------------------- | -| `repo-path` | The path in the repository to the kpt package | -| `repo-pkg-name` | The name of the kpt package in the repository | -| `pkg-version` | The version of the kpt package | -| `local-pkg-name` | The local name of the kpt package in the repository, defaults to `repo-pkg-name` | +| *repo-path* | The path in the repository to the kpt package | +| *repo-pkg-name* | The name of the kpt package in the repository | +| *pkg-version* | The version of the kpt package | +| *local-pkg-name* | The local name of the kpt package in the repository, defaults to *repo-pkg-name* | `kpt pkg get` make the following transformations: -1. The `metadata.name` field in the root `Kptfile` in the package is changed - from whatever value it has to `local-pkg-name` -2. The `metadata.namespace` field in the root `Kptfile` in the package is - removed -3. `upstream` and `upstreamlock` root fields are added to the root `Kptfile` as - follows: +1. The *metadata.name* field in the root *Kptfile* in the package is changed from whatever value it has to + *local-pkg-name* +2. The *metadata.namespace* field in the root *Kptfile* in the package is removed +3. *upstream* and *upstreamlock* root fields are added to the root *Kptfile* as follows: ```yaml upstream: @@ -49,10 +46,8 @@ upstreamLock: ref: commit: 0123456789abcdef0123456789abcdef01234567 ``` -4. The `data.name` field in the root `package-context.yaml` files is changed to - be `local-pkg-name` -5. The `package-context.yaml` file is added if it does not exist with the - following content: +4. The *data.name* field in the root *package-context.yaml* files is changed to be *local-pkg-name* +5. The *package-context.yaml* file is added if it does not exist with the following content: ```yaml apiVersion: v1 @@ -65,57 +60,51 @@ data: name: ``` -6. The `data.name` field in `package-context.yaml` files in the sub kpt packages is - changed to be the name of the sub package -7. All other sub-fields under the `data:` field are deleted -8. The comment `metadata: # kpt-merge: /` is added to root - `metadata` fields on all YAML documents in the kpt package and enclosed - sub-packages that have a root `apiVersion` and `kind` field if such a comment - does not already exist. The `namespace` and `name` values used are the values - of those fields in the `metadata` field. Note that a YAML file can contain - multiple YAML documents and each root `metadata` field is commented. For - example: - -```yaml -metadata: # kpt-merge: cert-manager/cert-manager-cainjector - name: cert-manager-cainjector - namespace: cert-manager -``` - -9. The annotation `internal.kpt.dev/upstream-identifier: - '|||'` is added to root - `metadata.annotations:` fields on all YAML documents in the kpt package and - enclosed sub-packages that have a root `apiVersion:` and `kind:` field if - such an annotation does not already exist. The `namespace` and `name` values - used are the values of those fields in the `metadata` field. Note that a YAML - file can contain multiple YAML documents and each root `metadata` field is - commented. For example: - -```yaml -metadata: # kpt-merge: cert-manager/cert-manager-cainjector -apiVersion: rbac.authorization.k8s.io/v1 -kind: RoleBinding -metadata: # kpt-merge: capi-kubeadm/leader-election-rolebinding - name: leader-election-rolebinding - namespace: capi-kubeadm - annotations: - internal.kpt.dev/upstream-identifier: 'rbac.authorization.k8s.io|RoleBinding|capi-kubeadm|leader-election-rolebinding' -``` +6. The *data.name* field in *package-context.yaml* files in the sub kpt packages is changed to be the name of the sub + package +7. All other sub-fields under the *data:* field are deleted +8. The comment *metadata: # kpt-merge: /* is added to root *metadata* fields on all YAML documents in + the kpt package and enclosed sub-packages that have a root *apiVersion* and *kind* field if such a comment does not + already exist. The *namespace* and *name* values used are the values of those fields in the *metadata* field. + {{% alert title="Note" color="primary" %}} + A YAML file can contain multiple YAML documents and each root *metadata* field is commented. For example: + + ```yaml + metadata: # kpt-merge: cert-manager/cert-manager-cainjector + name: cert-manager-cainjector + namespace: cert-manager + ``` + + {{% /alert %}} + +9. The annotation *internal.kpt.dev/upstream-identifier: '|||'* is added to root + *metadata.annotations:* fields on all YAML documents in the kpt package and enclosed sub-packages that have a root + *apiVersion:* and *kind:* field if such an annotation does not already exist. The *namespace* and *name* values + used are the values of those fields in the *metadata* field. Note that a YAML file can contain multiple YAML documents + and each root *metadata* field is commented. For example: + + ```yaml + metadata: # kpt-merge: cert-manager/cert-manager-cainjector + apiVersion: rbac.authorization.k8s.io/v1 + kind: RoleBinding + metadata: # kpt-merge: capi-kubeadm/leader-election-rolebinding + name: leader-election-rolebinding + namespace: capi-kubeadm + annotations: + internal.kpt.dev/upstream-identifier: 'rbac.authorization.k8s.io|RoleBinding|capi-kubeadm|leader-election-rolebinding' + ``` ### kpt fn render -The `kpt fn render ` runs kpt functions on a local package, thus -applying local changes to the package. +The `kpt fn render ` runs kpt functions on a local package, thus applying local changes to the package. -In the Nephio sandbox installation, kpt fn render only acts on the `repository` and -`rootsync` kpt packages from +In the Nephio sandbox installation, `kpt fn render` only acts on the *repository* and *rootsync* kpt packages from [nephio-example-packages](https://github.com/nephio-project/nephio-example-packages). #### repository package -The `repository` package has a kpt function written in -[starlark](https://github.com/bazelbuild/starlark), which is invoked by a -pipeline specified in the `kptfile`. +The *repository* package has a kpt function written in [starlark](https://github.com/bazelbuild/starlark), which is +invoked by a pipeline specified in the *kptfile*. ```yaml pipeline: @@ -124,48 +113,39 @@ pipeline: configPath: set-values.yaml ``` -The starlark function is specified in the `set-values.yaml` file. It makes the -following transformations on the repositories: - -1. In the file `repo-gitea.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.description` field gets the value of ` repository` -2. In the file `repo-porch.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.git.repo` field gets the value of - `"http://172.18.0.200:3000/nephio/.git` - - the `spec.git.secretRef.name` field gets the value of - `-access-token-porch` - - if the `` is called `mgmt-staging`, then the following extra - changes are made: - - the `spec.deployment` field is set to `false` (it defaults to `true`) - - the annotation `metadata.annotations.nephio.org/staging: "true"` is added -3. In the file `token-configsync.yaml` - - the `metadata.name` field gets the value of - `-access-token-configsync` - - the `metadata.namespace` field gets the value of `config-management-system` -4. In the file `token-porch.yaml` - - the `metadata.name` field gets the value of - `-access-token-porch` +The starlark function is specified in the *set-values.yaml* file. It makes the following transformations on the +repositories: + +1. In the file *repo-gitea.yaml* + - the *metadata.name* field gets the value of ** + - the *spec.description* field gets the value of * repository* +2. In the file *repo-porch.yaml* + - the *metadata.name* field gets the value of ** + - the *spec.git.repo* field gets the value of *`"http://172.18.0.200:3000/nephio/.git* + - the *spec.git.secretRef.name* field gets the value of *-access-token-porch* + - if the ** is called *mgmt-staging*, then the following extra changes are made: + - the *spec.deployment* field is set to *false* (it defaults to *true*) + - the annotation *metadata.annotations.nephio.org/staging: "true"* is added +3. In the file *token-configsync.yaml* + - the *metadata.name* field gets the value of *-access-token-configsync* + - the *metadata.namespace* field gets the value of *config-management-system* +4. In the file *token-porch.yaml* + - the *metadata.name() field gets the value of *-access-token-porch* #### rootsync Package -The `rootsync` package also has a kpt function written in -[starlark](https://github.com/bazelbuild/starlark) specified in the -`set-values.yaml` file. It makes the following transformations on repositories: +The *rootsync* package also has a kpt function written in [starlark](https://github.com/bazelbuild/starlark) specified +in the *set-values.yaml* file. It makes the following transformations on repositories: -1. In the file `rootsync.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.git.repo` field gets the value of - `"http://172.18.0.200:3000/nephio/.git` - - the `spec.git.secretRef.name` field gets the value of - `-access-token-configsync` +1. In the file *rootsync.yaml* + - the *metadata.name* field gets the value of ** + - the *spec.git.repo* field gets the value of *"http://172.18.0.200:3000/nephio/.git* + - the *spec.git.secretRef.name* field gets the value of *-access-token-configsync* ### kpt live init -The `kpt live init ` initializes a local package, making it -ready for application to a cluster. This command creates a `resourcegroup.yaml` -in the kpt package with content similar to: +The `kpt live init ` initializes a local package, making it ready for application to a cluster. This +command creates a *resourcegroup.yaml* in the kpt package with content similar to: ```yaml apiVersion: kpt.dev/v1alpha1 @@ -178,9 +158,8 @@ metadata: ``` ## porchctl rpkg for Workload clusters -The `porchctl rpkg` suite of commands that act on `Repository` resources on the -kubernetes cluster in scope. The packages in the `Repository` resources are -*remote packages (rpkg)*. +The `porchctl rpkg` suite of commands that act on *Repository* resources on the kubernetes cluster in scope. The +packages in the *Repository* resources are *remote packages (rpkg)*. To see which repositories are in scope: @@ -228,8 +207,6 @@ nephio-example-packages-fb6e4adecc13c50da838953ece623cf04de21884 ueransim nephio-example-packages-dc0b55fb7a17d107e834417a2c9d8fb37f36d7cb vlanindex v1 v1 true Published nephio-example-packages ``` - - To see the versions of a particular package: ```bash @@ -248,12 +225,10 @@ nephio-example-packages-7895e28d847c0296a204007ed577cd2a4222d1ea nephio-worklo ### Create the Workload cluster package -The Workload cluster package contains `PackageVariant` files for configuring the -new cluster. +The Workload cluster package contains *PackageVariant* files for configuring the new cluster. -Clone the `nephio-workload-cluster` package into the `mgmt` repository. This -creates the blueprint package for the workload cluster in the management -repository. +Clone the *nephio-workload-cluster* package into the *mgmt* repository. This creates the blueprint package for the +workload cluster in the management repository. ```bash porchctl rpkg clone -n default nephio-example-packages-7895e28d847c0296a204007ed577cd2a4222d1ea --repository mgmt regional @@ -261,67 +236,66 @@ porchctl rpkg clone -n default nephio-example-packages-7895e28d847c0296a204007ed During the clone operation, the command above performs the following operations: -1. It creates a `drafts/regional/v1` branch on the `mgmt` repository -2. It does the equivalent of a [kpt pkg get](#kpt-pkg-get) on the `nephio-workload-cluster` package into a directory +1. It creates a *drafts/regional/v1* branch on the *mgmt* repository +2. It does the equivalent of a [kpt pkg get](#kpt-pkg-get) on the *nephio-workload-cluster* package into a directory called `regional` on that branch, with the same transformations on package files carried out as the [kpt pkg get](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit -3. The pipeline specified in the `Kptfile`of the `nephio-workload-cluster` package specifies an `apply-replacements` - specified in the `apply-replacements.yaml` file in the package and uses the value of the - `package-context.yaml:data.name` field set in 2. above (which is the workload cluster name) as follows: - - - In all `PackageVariant` files, the `metadata.name` and `spec.downstream.package` field before the '-' is replaced +3. The pipeline specified in the *Kptfile* of the *nephio-workload-cluster* package specifies an *apply-replacements* + specified in the *apply-replacements.yaml* file in the package and uses the value of the + *package-context.yaml:data.name* field set in 2. above (which is the workload cluster name) as follows: + - In all *PackageVariant* files, the *metadata.name* and *spec.downstream.package* field before the '-' is replaced with that field value. In this way, the downstream package names for all the packages to be pulled from the - `mgmt-staging` repository for the workload cluster are specified. - - In all `PackageVariant` files, the `spec.injectors.WorkloadCluster.name` field is replaced with the workload - cluster name. This gives us the handle for `packageVariant` injection for the workload cluster in question. - - In all `PackageVariant` files, the - `spec.pipeline.mutators.[image=gcr.io/kpt-fn/set-annotations:v0.1.4].configMap.[nephio.org/cluster-name]` + *mgmt-staging* repository for the workload cluster are specified. + - In all *PackageVariant* files, the *spec.injectors.WorkloadCluster.name* field is replaced with the workload + cluster name. This gives us the handle for *packageVariant* injection for the workload cluster in question. + - In all *PackageVariant* files, the + *spec.pipeline.mutators.[image=gcr.io/kpt-fn/set-annotations:v0.1.4].configMap.[nephio.org/cluster-name]* field is replaced with the workload cluster name. - - In all `WorkloadCluster` files, the `metadata.name` and `spec.clusterName` fields are replaced with the workload + - In all *WorkloadCluster* files, the *metadata.name* and *spec.clusterName* fields are replaced with the workload cluster name. We now have a draft blueprint package for our workload cluster ready for further configuration. ### Configure the Package -We follow the instructions in the [installation README -file](https://github.com/nephio-project/test-infra/tree/main/e2e/provision). +We follow the instructions in the +[installation README file](https://github.com/nephio-project/test-infra/tree/main/e2e/provision). 1. Get the name of the package: -```bash -porchctl rpkg get | egrep '(NAME|regional)' -NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY -mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional v1 false Draft mgmt -``` + ```bash + porchctl rpkg get | egrep '(NAME|regional)' + NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY + mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional v1 false Draft mgmt + ``` 2. Pull the package to get a local copy of it: -```bash -porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional -``` + ```bash + porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional + ``` 3. Set the Nephio labels on the package: -```bash -kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site-type=regional" "nephio.org/region=us-west1" -``` + ```bash + kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site-type=regional" "nephio.org/region=us-west1" + ``` -4. Check that the labels have been set. In all `PackageVariant` and `WorkloadCluster` files, the following - `metadata.labels` fields have been added: +4. Check that the labels have been set. In all *PackageVariant* and *WorkloadCluster* files, the following + *metadata.labels* fields have been added: -```yaml -labels: - nephio.org/region: us-west1 - nephio.org/site-type: regional -``` + ```yaml + labels: + nephio.org/region: us-west1 + nephio.org/site-type: regional + ``` 5. Push the updated package back to the draft branch on the repository: -```bash -porchctl rpkg push -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional -[RUNNING] "gcr.io/kpt-fn/apply-replacements:v0.1.1" -[PASS] "gcr.io/kpt-fn/apply-replacements:v0.1.1" -``` + ```bash + porchctl rpkg push -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional + [RUNNING] "gcr.io/kpt-fn/apply-replacements:v0.1.1" + [PASS] "gcr.io/kpt-fn/apply-replacements:v0.1.1" + ``` ## Propose the Package @@ -332,14 +306,13 @@ porchctl rpkg propose -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 proposed ``` -Proposing the package changes the name of the `drafts/regional/v1` to -`proposed/regional/v1`. There are no changes to the content of the branch. +Proposing the package changes the name of the *drafts/regional/v1* to *proposed/regional/v1*. There are no changes to +the content of the branch. ### Approve the Package and Trigger Configsync -Approving the package triggers `configsync`, which triggers creation of the new -workload cluster using all the `PackageVariant` components specified in the -`nephio-workload-cluster` kpt package. +Approving the package triggers *configsync*, which triggers creation of the new workload cluster using all the +*PackageVariant* components specified in the *nephio-workload-cluster* kpt package. ```bash porchctl rpkg approve -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 @@ -350,20 +323,18 @@ The new cluster comes up after a number of minutes. ## Transformations in the Workload cluster creation -Approving the `regional` Workload cluster package in the `mgmt` repository -triggered configsync to apply the `PackageVariant` configurations in the -`mgmt/regional` package. Let's examine those `PackageVariant` configurations one +Approving the *regional* Workload cluster package in the *mgmt* repository triggered configsync to apply the +*PackageVariant* configurations in the *mgmt/regional* package. Let's examine those *PackageVariant* configurations one by one. -In the text below, let's assume we are creating a workload cluster called `lambda`. +In the text below, let's assume we are creating a workload cluster called *lambda*. ### pv-cluster.yaml: creates the Workload cluster -In the text below, let's assume we are creating a workload cluster called `lambda`. +In the text below, let's assume we are creating a workload cluster called *lambda*. -This package variant transformation results in a package variant of the -`cluster-capi-kind` package called `lambda-package`. The `lambda-package` -contains the definition of a pair custom resources that are created when the +This package variant transformation results in a package variant of the *cluster-capi-kind* package called +*lambda-package*. The *lambda-package* contains the definition of a pair custom resources that are created when the package is applied. The custom resource pair are instances of the CRDs below Custom Resource Definition | Controller | Function | @@ -371,113 +342,86 @@ Custom Resource Definition | Controller | Functi clusters.cluster.x-k8s.io | capi-system.capi-controller-manager | Trigger creation and start of the kind cluster | workloadclusters.infra.nephio.org | nephio-system.nephio-controller | Trigger addition of nephio-specific configuration to the kind cluster | -The `PackageVariant` specified in `pv-cluster.yaml` is executed and: +The *PackageVariant* specified in *pv-cluster.yaml* is ran and: + 1. Produces a package variant of the - [cluster-capi-kind](https://github.com/nephio-project/nephio-example-packages/tree/main/cluster-capi-kind) - package called `lambda-cluster` in the gitea `mgmt` repository on your management - cluster. -2. Applies the `lambda-cluster` kpt package to create the kind cluster for the - workload cluster. + [cluster-capi-kind](https://github.com/nephio-project/nephio-example-packages/tree/main/cluster-capi-kind) package + called *lambda-cluster* in the gitea *mgmt* repository on your management cluster. +2. Applies the *lambda-cluster* kpt package to create the kind cluster for the workload cluster. #### Package transformations During creation of the package variant kpt package, the following transformations occur: -1. It creates a `drafts/lambda-cluster/v1` branch on the `mgmt` repository -2. It does the equivalent of a [`kpt pkg get`](#kpt-pkg-get) on the `cluster-capi-kind` package into a directory called - `lambda-cluster` on that branch, with the same transformations on package files carried out as the +1. It creates a *drafts/lambda-cluster/v1* branch on the *mgmt* repository +2. It does the equivalent of a [`kpt pkg get`](#kpt-pkg-get) on the *cluster-capi-kind* package into a directory called + *lambda-cluster* on that branch, with the same transformations on package files carried out as the [`kpt pkg get`](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit -3. The pipeline specified in the `Kptfile`of the `cluster-capi-kind` package specifies an `apply-replacements` specified - in the `apply-replacements.yaml` file in the package and uses the value of the - `workload-cluster.yaml:spec.clusterName` field set in 2. above (which is the workload cluster name). This has the - value of `example` in the `workload-cluster.yaml` file. This means that in the `cluster.yaml` file the value of field - `metadata.name` is changed from `workload` to `example`. -4. The package variant `spec.injectors` changes specified in the `pv-cluster.yaml` file are applied.
a. The relevant - `pv-cluster.yaml` fields are: ``` spec: injectors: - - - kind: WorkloadCluster name: example pipeline: mutators: - - - image: gcr.io/kpt-fn/set-annotations:v0.1.4 configMap: - nephio.org/cluster-name: example ``` - - b. The following `PackageVariant` changes are made to the `lambda-cluster` package: - - 1. The field `info.readinessGates.conditionType` is added to the `Kptfile` with the value - `config.injection.WorkloadCluster.workload-cluster`. - 2. An extra `pipeline.mutators` entry is inserted in the `Kptfile`. This mutator is the mutator specified in the - `pv-cluster.yaml` package variant specification, which specifies that the annotation - `nephio.org/cluster-name: lambda` should be set on the resources in the package: +3. The pipeline specified in the *Kptfile* of the *cluster-capi-kind* package specifies an *apply-replacements* specified + in the *apply-replacements.yaml* file in the package and uses the value of the + *workload-cluster.yaml:spec.clusterName* field set in 2. above (which is the workload cluster name). This has the + value of *example* in the *workload-cluster.yaml* file. This means that in the *cluster.yaml* file the value of field + *metadata.name* is changed from *workload* to *example*. +4. The package variant *spec.injectors* changes specified in the *pv-cluster.yaml* file are applied. + 1. The relevant *pv-cluster.yaml* fields are: ```yaml - pipeline: - mutators: - - name: PackageVariant.lambda-cluster..0 - image: gcr.io/kpt-fn/set-annotations:v0.1.4 + spec: + injectors: + - kind: WorkloadCluster name: example + pipeline: + mutators: + - image: gcr.io/kpt-fn/set-annotations:v0.1.4 configMap: - nephio.org/cluster-name: lambda - ``` - 3. The field `status.conditions` is added to the `Kptfile` with the values below. This condition means that the - kpt package is not considered to be applied until the condition `config.injection.WorkloadCluster.workload-cluster` is `True`: - - ```yaml - status: - conditions: - - type: config.injection.WorkloadCluster.workload-cluster - status: "True" - message: injected resource "lambda" from cluster - reason: ConfigInjected + nephio.org/cluster-name: example ``` - 4. The `spec` in the WorkloadCluster file `workload-cluster.yaml` is set. This is the specification of the extra - configuration that will be carried out on the workload cluster once kind has brought it up: - ```yaml - clusterName: lambda - cnis: - - macvlan - - ipvlan - - sriov - masterInterface: eth1 - ``` -5. The amended pipeline specified in the `Kptfile`of the `lambda-cluster` is now re-executed. It was previously executed + 2. The following *PackageVariant* changes are made to the *lambda-cluster* package: + + 1. The field *info.readinessGates.conditionType* is added to the *Kptfile* with the value + *config.injection.WorkloadCluster.workload-cluster*. + 2. An extra *pipeline.mutators* entry is inserted in the *Kptfile*. This mutator is the mutator specified in the + *pv-cluster.yaml* package variant specification, which specifies that the annotation + *nephio.org/cluster-name: lambda* should be set on the resources in the package: + + ```yaml + pipeline: + mutators: + - name: PackageVariant.lambda-cluster..0 + image: gcr.io/kpt-fn/set-annotations:v0.1.4 + configMap: + nephio.org/cluster-name: lambda + ``` + 3. The field *status.conditions* is added to the *Kptfile* with the values below. This condition means that the + kpt package is not considered to be applied until the condition + *config.injection.WorkloadCluster.workload-cluster* is *True*: + + ```yaml + status: + conditions: + - type: config.injection.WorkloadCluster.workload-cluster + status: "True" + message: injected resource "lambda" from cluster + reason: ConfigInjected + ``` + 4. The *spec* in the *WorkloadCluster* file *workload-cluster.yaml* is set. This is the specification of the extra + configuration that will be carried out on the workload cluster once kind has brought it up: + + ```yaml + clusterName: lambda + cnis: + - macvlan + - ipvlan + - sriov + masterInterface: eth1 + ``` +5. The amended pipeline specified in the *Kptfile* of the *lambda-cluster* is now re-executed. It was previously executed in step 3 above but there is now an extra mutator added by the package variant. The following changes result: + 1. The new mutator added to the *Kptfile* by the package variant adds the annotation + *nephio.org/cluster-name: lambda* is added to every resource in the package. + 2. The existing annotation in the *Kptfile* (coming from the Kptfile in the parent *cluster-capi-kind* package) sets + the value *lambda* of the *spec.clusterName* field in *workload-cluster.yaml* as the value of the *metadata.name* + field in the *cluster.yaml* file. - a. The new mutator added to the `Kptfile` by the package variant adds the annotation - `nephio.org/cluster-name: lambda` is added to every resource in the package. - b. The existing annotation in the `Kptfile` (coming from the Kptfile in the parent `cluster-capi-kind` package) sets - the value `lambda` of the `spec.clusterName` field in `workload-cluster.yaml` as the value of the `metadata.name` - field in the `cluster.yaml` file. - -6. The `lambda-cluster` package is now ready to go. It is proposed and approved and the process of cluster creation +6. The *lambda-cluster* package is now ready to go. It is proposed and approved and the process of cluster creation commences. - -#### Cluster Creation - -TBD. - -### pv-rootsync.yaml: - -TBD. - -### pv-repo.yaml: create the workload cluster repository - -TBD. - -### pv-configsync.yaml: - -TBD. - -### pv-kindnet.yaml: - -TBD. - -### pv-local-path-provisioner.yaml: - -TBD. - -### pv-multus.yaml: - -TBD. - -### pv-vlanindex.yaml: - -TBD. diff --git a/content/en/docs/guides/install-guides/webui-auth-gcp.md b/content/en/docs/guides/install-guides/webui-auth-gcp.md index 5ef070a5..9ee7860a 100644 --- a/content/en/docs/guides/install-guides/webui-auth-gcp.md +++ b/content/en/docs/guides/install-guides/webui-auth-gcp.md @@ -7,10 +7,10 @@ weight: 7 --- -When used with the Web UI running in a GKE cluster, the users authorization roles will be automatically synchronized +When used with the WebUI running in a GKE cluster, the users authorization roles will be automatically synchronized based upon their IAM roles in GCP. -If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you +If you are not exposing the WebUI on a load balancer IP address, but are instead using `kubectl port-forward`, you should use `http`, `localhost` and `7007` for the `SCHEME`, `HOSTNAME` and `PORT`; otherwise, use the scheme, DNS name and port as it will be seen by your browser. You can leave the port off if it is 443 for HTTPS or 80 for HTTP. @@ -49,7 +49,7 @@ kubectl create secret generic -n nephio-webui nephio-google-oauth-client --from- ## Enable Google OAuth -The webui package has a function that will configure the package for authentication with different services. Edit the +The WebUI package has a function that will configure the package for authentication with different services. Edit the `set-auth.yaml` file to set the `authProvider` field to `google` or run this command: ```bash @@ -57,7 +57,7 @@ kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-nam ``` ## Enable OIDC with Google -The webui package has a function that will configure the package for authentication with different services. Edit the +The WebUI package has a function that will configure the package for authentication with different services. Edit the `set-auth.yaml` file to set the `authProvider` field to `oidc` and the `oidcTokenProvider` to `google`, or run these commands: diff --git a/content/en/docs/guides/install-guides/webui-auth-okta.md b/content/en/docs/guides/install-guides/webui-auth-okta.md index b3d011c5..84b82b7f 100644 --- a/content/en/docs/guides/install-guides/webui-auth-okta.md +++ b/content/en/docs/guides/install-guides/webui-auth-okta.md @@ -5,7 +5,7 @@ description: > weight: 7 --- -If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you +If you are not exposing the WebUI on a load balancer IP address, but are instead using `kubectl port-forward`, you should use `localhost` and `7007` for the `HOSTNAME` and `PORT`; otherwise, use the DNS name and port as it will be seen by your browser. @@ -26,8 +26,8 @@ documentation: - App integration name: Nephio Web UI (or any other name you wish) - Grant type: Authorization Code & Refresh Token - - Sign-in redirect URIs: http://HOSTNAME:PORT/api/auth/okta/handler/frame - - Sign-out redirect URIs: http://HOSTNAME:PORT + - Sign-in redirect URIs: *http://HOSTNAME:PORT/api/auth/okta/handler/frame* + - Sign-out redirect URIs: *http://HOSTNAME:PORT* - Controlled access: (select as appropriate) - Click Save @@ -38,13 +38,13 @@ container environment. In the secret, use these keys: -| Key | Description | -| -------------- | ----------------------------------------------------------- | -| client-id | The client ID that you generated on Okta, e.g. 3abe134ejxzF21HU74c1 | -| client-secret | The client secret shown for the Application. | -| audience | The Okta domain shown for the Application, e.g. https://www.okta.com/company/ | -| auth-server-id | The authorization server ID for the Application (optional) | -| idp | The identity provider for the application, e.g. 0oaulob4BFVa4zQvt0g3 (optional) | +| Key | Description | +| ---------------- | ------------------------------------------------------------------------------- | +| *client-id* | The client ID that you generated on Okta, e.g. 3abe134ejxzF21HU74c1 | +| *client-secret* | The client secret shown for the Application. | +| *audience* | The Okta domain shown for the Application, e.g. *https://www.okta.com/company/* | +| *auth-server-id* | The authorization server ID for the Application (optional) | +| *idp* | The identity provider for the application, e.g. 0oaulob4BFVa4zQvt0g3 (optional) | This can be done via a secrets manager or by manually provision the secret (replacing the placeholders here): @@ -60,7 +60,7 @@ kubectl create secret generic -n nephio-webui nephio-okta-oauth-client \ ## Enable the WebUI Auth Provider -The webui package has a function that will configure the package for authentication with different services. Edit the +The WebUI package has a function that will configure the package for authentication with different services. Edit the `set-auth.yaml` file to set the `authProvider` field to `oidc` and the `oidcTokenProvider` to `okta`, or run these commands: From 565c8a033bf94e5a95c06070a32aa29f2fb333bb Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Wed, 23 Oct 2024 23:23:27 +0300 Subject: [PATCH 43/74] Linkcheck corrections, correctons based on Vale suggestions Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 6 +- .linkspector.yml | 1 + .vale/config/vocabularies/Nephio/accept.txt | 2 + .../install-guides/package-transformations.md | 4 +- .../docs/guides/user-guides/helm/flux-helm.md | 26 ++++----- ...helm-to-operator-codegen-sdk-user-guide.md | 58 +++++++++++++------ 6 files changed, 63 insertions(+), 34 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 886120d0..f0693a60 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -17,14 +17,16 @@ jobs: egress-policy: audit - name: Install prerequisites run: | - sudo apt-get --allow-releaseinfo-change update -y && sudo apt-get install -y python3-sphinx + sudo apt-get --allow-releaseinfo-change update -y && sudo apt-get install -y docutils - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog env: - REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.VALE_GITHUB_TOKEN }} + REVIEWDOG_GITHUB_API_TOKEN: ${{secrets.VALE_GITHUB_TOKEN}} with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check # more info on these: https://github.com/reviewdog/reviewdog#reporters reporter: github-pr-check + fail_on_error: false + filter_mode: nofilter token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file diff --git a/.linkspector.yml b/.linkspector.yml index 00e62e46..13439c64 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -11,6 +11,7 @@ ignorePatterns: - pattern: "^http://localhost.*$" - pattern: "^http://HOSTNAME:PORT.*$" - pattern: "172\\.18\\.255\\.200" + - pattern: "172\\.18\\.0\\.200" replacementPatterns: - pattern: ".md#.*$" replacement: ".md" diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 735db924..205a314c 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -9,6 +9,7 @@ ASNs [Aa]utoscaling cabundle [Cc]onfigmap +Codegen [Cc]loudified CLI CRD @@ -57,6 +58,7 @@ passwordless Postgres [Rr]pkg rootsync +SDK starlark stdout stderr diff --git a/content/en/docs/guides/install-guides/package-transformations.md b/content/en/docs/guides/install-guides/package-transformations.md index 05106265..7c0cbdb8 100644 --- a/content/en/docs/guides/install-guides/package-transformations.md +++ b/content/en/docs/guides/install-guides/package-transformations.md @@ -121,7 +121,7 @@ repositories: - the *spec.description* field gets the value of * repository* 2. In the file *repo-porch.yaml* - the *metadata.name* field gets the value of ** - - the *spec.git.repo* field gets the value of *`"http://172.18.0.200:3000/nephio/.git* + - the *spec.git.repo* field gets the value of *http://172.18.0.200:3000/nephio/.git* - the *spec.git.secretRef.name* field gets the value of *-access-token-porch* - if the ** is called *mgmt-staging*, then the following extra changes are made: - the *spec.deployment* field is set to *false* (it defaults to *true*) @@ -139,7 +139,7 @@ in the *set-values.yaml* file. It makes the following transformations on reposit 1. In the file *rootsync.yaml* - the *metadata.name* field gets the value of ** - - the *spec.git.repo* field gets the value of *"http://172.18.0.200:3000/nephio/.git* + - the *spec.git.repo* field gets the value of *http://172.18.0.200:3000/nephio/.git* - the *spec.git.secretRef.name* field gets the value of *-access-token-configsync* ### kpt live init diff --git a/content/en/docs/guides/user-guides/helm/flux-helm.md b/content/en/docs/guides/user-guides/helm/flux-helm.md index 8a0e2546..236a0631 100644 --- a/content/en/docs/guides/user-guides/helm/flux-helm.md +++ b/content/en/docs/guides/user-guides/helm/flux-helm.md @@ -24,9 +24,9 @@ Then, we can utilize the flux Custom Resources defined in another test kpt packa ### Deploying the flux-helm-controllers pkg -Access the Nephio Web UI and execute the following: +Access the Nephio WebUI and do following steps: -We will deploy the `flux-helm-controllers` pkg from the `nephio-example-packages` repo to the `edge02` workload +We will deploy the *flux-helm-controllers* pkg from the *nephio-example-packages* repository to the `edge02` workload cluster. * **Step 1** @@ -41,23 +41,23 @@ cluster. ![Install flux controllers - Step 3](/static/images/user-guides/flux-controller-selection.png) -Click through the `Next` button until you are through all the steps, leaving all options as `default`, then click -`Create Deployment`. +Click through the *Next* button until you are through all the steps, leaving all options as *default*, then click +*Create Deployment*. * **Step 4** ![Install flux controllers - Step 4](/static/images/user-guides/select-create-deployment.png) -At this point, we can take a closer look at the contents of the kpt package which contains the relevant kubernetes +At this point, we can take a closer look at the contents of the kpt package which contains the relevant Kubernetes resources to deploy the controllers. {{% alert title="Note" color="primary" %}} -We are deploying into the `flux-system` namespace by default. +We are deploying into the *flux-system* namespace by default. {{% /alert %}} -Finally, we need to `propose` and then `approve` the pkg to initialize the deployment. +Finally, we need to *propose* and then *approve* the pkg to initialize the deployment. * **Step 5** @@ -85,7 +85,7 @@ source-controller-5756bf7d48-hprkn 1/1 Running 0 6m20s ### Deploying the onlineboutique-flux pkg -To make the demo kpt packages available in Nephio, we need to register a new `External Blueprints`repository. We can do +To make the demo kpt packages available in Nephio, we need to register a new *External Blueprints* repository. We can do this via kubectl towards the management cluster. ```bash @@ -109,7 +109,7 @@ spec: EOF ``` -The new repository should now have been added to the `External Blueprints` section of the UI. +The new repository should now have been added to the *External Blueprints* section of the UI. ![External Blueprints UI](/static/images/user-guides/external-bp-repos.png) @@ -118,14 +118,14 @@ From here, we can see the onlineboutique-flux pkg to be deployed. ![online boutique pkg](/static/images/user-guides/nephio-pkgs-onlineboutique-show.png) The HelmRepository Custom Resource within the kpt pkg refers to the official -[online boutique helm charts repo.](https://github.com/GoogleCloudPlatform/microservices-demo/tree/main/helm-chart) +[online boutique helm charts repository.](https://github.com/GoogleCloudPlatform/microservices-demo/tree/main/helm-chart) -![HelmRepo online boutique ref](/static/images/user-guides/helmrepo-onlineboutique-ref.png) +![Helm repoository online boutique ref](/static/images/user-guides/helmrepo-onlineboutique-ref.png) To deploy the pkg, repeat/follow **Steps 1 - 6** from above, replacing **Step 3** with the following. Take note of the -source repo and the package to be deployed. +source repository and the package to be deployed. -![Add acm pkg](/static/images/user-guides/add-deploy-onlinebout-select.png) +![Add ACM pkg](/static/images/user-guides/add-deploy-onlinebout-select.png) {{% alert title="Note" color="primary" %}} diff --git a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md index eb6c2e5a..be6735bd 100644 --- a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md +++ b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md @@ -1,35 +1,50 @@ --- -title: Helm to Operator Codegen Sdk +title: Helm to Operator Codegen SDK description: > - Deploying helm charts in Nephio using Helm To Operator Codegen Sdk + Deploying helm charts in Nephio using Helm To Operator Codegen SDK weight: 1 --- -The [Helm to Operator Codegen SDK](https://github.com/nephio-project/nephio-sdk/tree/main/helm-to-operator-codegen-sdk) offers a streamlined solution for translating existing Helm charts into Kubernetes operators with minimal effort and cost. +The [Helm to Operator Codegen SDK](https://github.com/nephio-project/nephio-sdk/tree/main/helm-to-operator-codegen-sdk) +offers a streamlined solution for translating existing Helm charts into Kubernetes operators with minimal effort and +cost. -By utilizing the Helm to Operator Codegen SDK, users can efficiently convert existing Helm charts into Kubernetes operators. This transition enables users to leverage the advanced capabilities provided by Kubernetes operators, such as enhanced automation, lifecycle management, and custom logic handling. Overall, the SDK facilitates a smooth migration process, empowering users to embrace the operator model for managing their Kubernetes resources effectively. +By utilizing the Helm to Operator Codegen SDK, users can efficiently convert existing Helm charts into Kubernetes +operators. This transition enables users to leverage the advanced capabilities provided by Kubernetes operators, such as +enhanced automation, lifecycle management, and custom logic handling. Overall, the SDK facilitates a smooth migration +process, empowering users to embrace the operator model for managing their Kubernetes resources effectively. ## Exercise: Deploying Free5gc using operator -In the following exercise, the objective is to convert the Free5gc Helm chart to Go code suitable for a Kubernetes operator using the sdk. Once the conversion is complete, the generated Go code will be used to deploy all the resources defined in the Free5gc Helm chart using a Kubernetes operator. + +In the following exercise, the objective is to convert the Free5gc Helm chart to Go code suitable for a Kubernetes +operator using the SDK. Once the conversion is complete, the generated Go code will be used to deploy all the resources +defined in the Free5gc Helm chart using a Kubernetes operator. ### Step 0: Prerequisite + 1. GoLang Version: 1.21 2. Helm : v3.9.3 3. Kubebuilder -4. A Kubernetes Cluster with Calico CNI and multus-cni plugin (Can Refer [here](https://medium.com/rahasak/deploying-5g-core-network-with-free5gc-kubernets-and-helm-charts-29741cea3922), Before "Deploy Helm-Chart Part" ) +4. A Kubernetes Cluster with Calico CNI and multus-cni plugin (Can Refer + [here](https://medium.com/rahasak/deploying-5g-core-network-with-free5gc-kubernets-and-helm-charts-29741cea3922), + Before "Deploy Helm-Chart Part" ) 5. Go Packages: -``` -# Clone the Repo -git clone https://github.com/nephio-project/nephio-sdk.git -cd nephio-sdk/helm-to-operator-codegen-sdk/ -go mod tidy -``` + + ```bash + # Clone the Repo + git clone https://github.com/nephio-project/nephio-sdk.git + cd nephio-sdk/helm-to-operator-codegen-sdk/ + go mod tidy + ``` ### Step 1: Convert the helm-chart to Go-Code using Helm-to-operator-codegen-sdk -Currently, only Local-Helm charts are supported by sdk, Therefore, the first step would be to download the free5gc-Helm-Chart. (Refer [here](https://github.com/Orange-OpenSource/towards5gs-helm/tree/main)) + +Currently, only Local-Helm charts are supported by SDK, Therefore, the first step would be to download the +free5gc-Helm-Chart. (Refer [here](https://github.com/Orange-OpenSource/towards5gs-helm/tree/main)) To initiate the conversion process using the SDK, you can use the following command: -``` + +```bash go run main.go where: : Path to your local chart, the folder must contain a chart.yaml file. @@ -39,7 +54,8 @@ where: ``` -#### Example Run +#### Example Run + ``` go run main.go /home/ubuntu/free5gccharts/towards5gs-helm/charts/free5gc/ free5gcns info ``` @@ -274,8 +290,16 @@ The generated Go-Code would be written to the "outputs/generated_code.go" file The Generated Go-Code shall contain the following functions: #### A) Pluggable functions -1. CreateAll(): When called, it will create all the k8s resources(services, deployment) on the kubernetes cluster. (Note: For your Reconciler to call the function, Replace `YourKindReconciler` with the type of your Reconciler) -2. DeleteAll(): When called, it will delete all the k8s resources(services, deployment) on the kubernetes cluster. (Note: For your Reconciler to call the function, Replace `YourKindReconciler` with the type of your Reconciler) + +1. CreateAll(): When called, it will create all the k8s resources(services, deployment) on the kubernetes cluster. + {{% alert title="Note" color="primary" %}} + For your Reconciler to call the function, Replace *YourKindReconciler* with the type of your Reconciler + {{% /alert %}} + +2. DeleteAll(): When called, it will delete all the k8s resources(services, deployment) on the kubernetes cluster. + {{% alert title="Note" color="primary" %}} + For your Reconciler to call the function, Replace *YourKindReconciler* with the type of your Reconciler + {{% /alert %}} 3. Getxxx(): Shall return the list of a particular resource. 1. GetService(): Shall return the list of all services. 2. GetDeployment(): Shall return the list of all deployments. & so on From 53b63b26c4d00186196ba9fff5a589e3ba5ae24c Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 24 Oct 2024 14:43:24 +0300 Subject: [PATCH 44/74] Fix vale errors - Moving the env statement in the GitHub workflow - Printing the environment in the ocntext of vale - Adding workds to the accept list - Fixing findings Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 6 +- .vale/config/vocabularies/Nephio/accept.txt | 6 ++ content/en/docs/guides/_index.md | 2 +- .../contributor-guides/documentation.md | 2 +- .../contributor-guides/minimal-environment.md | 36 ++++---- .../guides/install-guides/install-on-gcp.md | 19 ++--- .../en/docs/guides/user-guides/controllers.md | 14 ++-- .../docs/guides/user-guides/exercise-2-oai.md | 82 ++++++++++--------- .../en/docs/guides/user-guides/helm/_index.md | 5 +- ...helm-to-operator-codegen-sdk-user-guide.md | 26 ++++-- 10 files changed, 108 insertions(+), 90 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index f0693a60..053764df 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -3,6 +3,9 @@ on: pull_request: workflow_dispatch: +env: + REVIEWDOG_GITHUB_API_TOKEN: ${{secrets.VALE_GITHUB_TOKEN}} + jobs: vale: name: runner / vale @@ -18,10 +21,9 @@ jobs: - name: Install prerequisites run: | sudo apt-get --allow-releaseinfo-change update -y && sudo apt-get install -y docutils + env - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog - env: - REVIEWDOG_GITHUB_API_TOKEN: ${{secrets.VALE_GITHUB_TOKEN}} with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 205a314c..8fc0a143 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -11,11 +11,13 @@ cabundle [Cc]onfigmap Codegen [Cc]loudified +Containerlab CLI CRD CRDs Crossplane Dockerfile +Docsy envtest [Ee]tcd gcloud @@ -26,16 +28,20 @@ GitOps Graphviz [Hh]ostname [Hh]omebrew +html [Kk]pt [Kk]ptfile kubeadm +Kubebuilder kubectl kubelet Kubernetes Kustomize Libvirt +MetalLB [Nn]amespace Nephio +Netlify NF NFDeploy NFDeployment diff --git a/content/en/docs/guides/_index.md b/content/en/docs/guides/_index.md index 6fa63f4b..2b7e0ff7 100644 --- a/content/en/docs/guides/_index.md +++ b/content/en/docs/guides/_index.md @@ -5,7 +5,7 @@ weight: 2 --- {{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clearly done. +This page is draft and the separation of the content to different categories is not done. {{% /pageinfo %}} diff --git a/content/en/docs/guides/contributor-guides/documentation.md b/content/en/docs/guides/contributor-guides/documentation.md index bf131a7b..96c9cb2a 100644 --- a/content/en/docs/guides/contributor-guides/documentation.md +++ b/content/en/docs/guides/contributor-guides/documentation.md @@ -10,7 +10,7 @@ weight: 5 The Nephio documentation is built with the .md / Hugo / Docsy / Netlify framework. * **.md:** The documentation itself is written in Markdown (,md) with some Hugo and Docsy related extensions. The .md - files are stored and managed in a Git repo in [nephio-project/docs](https://github.com/nephio-project/docs). + files are stored and managed in a Git repository in [nephio-project/docs](https://github.com/nephio-project/docs). * **Hugo:** [Hugo](https://gohugo.io/) is used to render the documentation fo static html pages. * **Docsy:** [Docsy](https://www.docsy.dev/) is a theme for Hugo what we use to provide the basic structure and look and feel of the documentation. diff --git a/content/en/docs/guides/contributor-guides/minimal-environment.md b/content/en/docs/guides/contributor-guides/minimal-environment.md index cf762bca..744c8fe7 100644 --- a/content/en/docs/guides/contributor-guides/minimal-environment.md +++ b/content/en/docs/guides/contributor-guides/minimal-environment.md @@ -5,13 +5,16 @@ description: > weight: 5 --- -The following environment install works on a MacBook Pro M1 or via SSH to Ubuntu 22.04 to get the nephio-operators running in vscode talking to a local kind cluster running in Docker. Note that depending on what part of Nephio you are working on, you may wish to install less or more of the components below. It should work on other environments with appropriate tweaking. +The following environment install works on a MacBook Pro M1 or via SSH to Ubuntu 22.04 to get the nephio-operators +running in VS Code talking to a local kind cluster running in Docker. Note that depending on what part of Nephio you are +working on, you may wish to install less or more of the components below. It should work on other environments with +appropriate tweaking. ## Install Docker, kind, and kpt packages This script automates steps 3 to 9 below. -```sh +```bash #!/usr/bin/env bash cat </dev/null || exit ### Installation steps: 1. [Install Docker](https://docs.docker.com/engine/install/) using the appropriate method for your system. - -2. [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) using the appropriate method for your system (homebrew on mac) - -3. [Install kpt cli](https://kpt.dev/installation/kpt-cli) using the appropriate method for your system (e.g. homebrew on mac) - +2. [Install kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) using the appropriate method for your + system (homebrew on mac) +3. [Install kpt CLI](https://kpt.dev/installation/kpt-cli) using the appropriate method for your system (e.g. homebrew + on mac) 4. Create the management cluster -```sh +```bash kind create cluster -n mgmt ``` -5. Install gitea +5. Install Gitea -```sh +```bash kpt pkg get https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@main gitea kpt live init gitea kpt live apply gitea ``` -6. Make gitea visible on host machine +6. Make Gitea visible on host machine -```sh +```bash kubectl port-forward -n gitea svc/gitea 3000:3000 ``` 7. Install Porch -```sh +```bash kpt pkg get https://github.com/nephio-project/catalog.git/nephio/core/porch@main porch kpt live init porch kpt live apply porch @@ -75,7 +77,7 @@ kpt live apply porch 8. Install configsync -```sh +```bash kpt pkg get https://github.com/nephio-project/catalog.git/nephio/core/configsync@main configsync kpt live init configsync kpt live apply configsync @@ -83,7 +85,7 @@ kpt live apply configsync 9. Install the resource backend -```sh +```bash kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/resource-backend@main resource-backend kpt live init resource-backend kpt live apply resource-backend @@ -91,7 +93,7 @@ kpt live apply resource-backend 10. Load the Nephio CRDs -```sh +```bash kpt pkg get https://github.com/nephio-project/catalog/tree/main/nephio/core/nephio-operator nephio-operator ls nephio-operator/crd/bases/*.yaml | xargs -n1 kubectl apply -f ``` @@ -102,7 +104,7 @@ Connecting to Gitea allows you to see the actions that Nephio takes on Gitea. 1. Port forward the Gitea port to your localhost -```sh +```bash kubectl port-forward -n gitea svc/gitea 3000:3000 ``` diff --git a/content/en/docs/guides/install-guides/install-on-gcp.md b/content/en/docs/guides/install-guides/install-on-gcp.md index 49790f85..dd13af65 100644 --- a/content/en/docs/guides/install-guides/install-on-gcp.md +++ b/content/en/docs/guides/install-guides/install-on-gcp.md @@ -10,7 +10,7 @@ In this guide, you will set up Nephio with: - **Management Cluster**: GKE Standard with auto scaling enabled - **Cluster Provisioner**: Kubernetes Config Connector (KCC), hosted as a managed service via Config Controller (CC). - **Workload Clusters**: GKE -- **Gitops Tool**: Config Sync +- **GitOps Tool**: Config Sync - **Git Provider**: Google Cloud Source Repositories will be the git provider for cluster deployment repositories. Some external repositories will be on GitHub. - **Web UI Auth**: Google OAuth 2.0 @@ -506,7 +506,7 @@ Project [your-nephio-project-id] repository [config-control] was cloned to [/hom Before you start adding things to that repository, set up Config Sync to pull configurations from there by creating a -RootSync in Config Controller. There is a package available to help properly configure the RootSync: +rootsync in Config Controller. There is a package available to help properly configure the rootsync: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/gcp/cc-rootsync@main @@ -583,7 +583,7 @@ Successfully executed 2 function(s) in 1 package(s). In the sandbox exercises, you may have used `kpt live apply` to apply the package at this point. In this case, there are restrictions in Config Controller that interfere with the operation of `kpt live`. So, instead, you can just directly -apply the RootSync resources with `kubectl`: +apply the rootsync resources with `kubectl`: ```bash kubectl apply -f cc-rootsync/rootsync.yaml @@ -687,9 +687,9 @@ kubectl describe rootsync -n config-management-system root-sync Name: root-sync Namespace: config-management-system Labels: -Annotations: internal.kpt.dev/upstream-identifier: configsync.gke.io|RootSync|config-management-system|root-sync +Annotations: internal.kpt.dev/upstream-identifier: configsync.gke.io|rootsync|config-management-system|root-sync API Version: configsync.gke.io/v1beta1 -Kind: RootSync +Kind: rootsync Metadata: Creation Timestamp: 2023-09-11T16:31:50Z Generation: 1 @@ -888,7 +888,7 @@ Customized package for deployment. Create a local commit, but do not push it to the upstream repository yet. As before, this is just to allow `git diff` -to easily identify the you make later. +to identify the changes you make later. ```bash git add nephio-mgmt/ @@ -1226,8 +1226,7 @@ Record addition appended to transaction at [transaction.yaml]. -Execute the transaction to store the record. Depending on your DNS -configuration, it may take some time to be resolvable. +Run the transaction to store the record. Depending on your DNS configuration, it may take some time to be resolvable. ```bash gcloud dns record-sets transaction execute --zone=$MANAGED_ZONE @@ -1253,8 +1252,8 @@ shown below: ## Some Exercises -As a an exercise to get started, you can create edge clusters by using `kubectl` -to apply the following following PackageVariantSet to your management cluster: +As a an exercise to get started, you can create edge clusters by using `kubectl` to apply the following +PackageVariantSet to your management cluster: ```yaml apiVersion: config.porch.kpt.dev/v1alpha2 diff --git a/content/en/docs/guides/user-guides/controllers.md b/content/en/docs/guides/user-guides/controllers.md index 079e5e7e..36110c1f 100644 --- a/content/en/docs/guides/user-guides/controllers.md +++ b/content/en/docs/guides/user-guides/controllers.md @@ -14,10 +14,10 @@ are used by Kubernetes to enforce the desired state of a Custom Resource (CR). The Nephio Controller deploys multiple reconcilers and also supports pluggable reconcilers. To plug into the Nephio controller, a reconciler must implement the -[nephio reconcilerinterface](https://github.com/nephio-project/nephio/tree/main/controllers/pkg/reconcilers/reconciler-interface). +[Nephio reconciler interface](https://github.com/nephio-project/nephio/tree/main/controllers/pkg/reconcilers/reconciler-interface). Reconcilers register with the Nephio reconciler interface when they start up. -The reconcilers below are currently deployed by default in the nephio controller: +The reconcilers below are currently deployed by default in the Nephio controller: ```bash ./controllers/pkg/reconcilers/token/reconciler.go @@ -33,12 +33,10 @@ The reconcilers below are currently deployed by default in the nephio controller ## Enabling Reconcilers -To enable a particular reconciler, you pass an environment variable to the -Nephio Controller at startup. The environment variable is of the form -`ENABLE_` where `` is the name of the reconciler to -be enabled in upper case. Therefore, to enable the `bootstrap-packages` reconciler, -pass the `ENABLE_BOOTSTRAPPACKAGES` to the nephio controller. Reconcilers are -disabled by default. +To enable a particular reconciler, you pass an environment variable to the Nephio Controller at startup. The environment +variable is of the form `ENABLE_` where `` is the name of the reconciler to be enabled in upper +case. Therefore, to enable the `bootstrap-packages` reconciler, pass the `ENABLE_BOOTSTRAPPACKAGES` to the Nephio +controller. Reconcilers are disabled by default. You can see what reconcilers are enabled on the Nephio Controller using diff --git a/content/en/docs/guides/user-guides/exercise-2-oai.md b/content/en/docs/guides/user-guides/exercise-2-oai.md index cf7b90a8..bf7fcf22 100644 --- a/content/en/docs/guides/user-guides/exercise-2-oai.md +++ b/content/en/docs/guides/user-guides/exercise-2-oai.md @@ -62,7 +62,7 @@ kubectl get repositories The output is similar to: -```console +```bash NAME TYPE CONTENT DEPLOYMENT READY ADDRESS catalog-distros-sandbox git Package false True https://github.com/nephio-project/catalog.git catalog-infra-capi git Package false True https://github.com/nephio-project/catalog.git @@ -86,14 +86,16 @@ kubectl apply -f test-infra/e2e/tests/oai/001-infra.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/oai-core-clusters-mgmt-core created packagevariantset.config.porch.kpt.dev/oai-regional-clusters created packagevariantset.config.porch.kpt.dev/oai-edge-clusters created ``` -It will take around 15 mins to create the three clusters. You can check the progress by looking at commits made in gitea `mgmt` and `mgmt-staging` repository. After couple of minutes you should see three independent repositories (Core, Regional and Edge) for each workload cluster. +It will take around 15 minutess to create the three clusters. You can check the progress by looking at commits made in +Gitea `mgmt` and `mgmt-staging` repository. After couple of minutes you should see three independent repositories (Core, +Regional and Edge) for each workload cluster. You can also look at the state of `packagerevisions` for the three packages. You can use the below command @@ -117,7 +119,7 @@ kubectl get clusters.cluster.x-k8s.io The output is similar to: -```console +```bash NAME CLUSTERCLASS PHASE AGE VERSION core docker Provisioned 34m v1.26.3 edge docker Provisioned 34m v1.26.3 @@ -145,7 +147,7 @@ kubectl get ns --context core-admin@core The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 33m config-management-system Active 33m @@ -168,7 +170,7 @@ kubectl get machinesets The output is similar to: -```console +```bash NAME CLUSTER REPLICAS READY AVAILABLE AGE VERSION core-md-0-fwksw-fqmq7 core 1 1 1 2m28s v1.26.3 edge-md-0-2z48t-bktd2 edge 1 1 1 2m28s v1.26.3 @@ -176,7 +178,8 @@ regional-md-0-mwnzd-4kl4h regional 1 1 1 2m28s v1 ``` -Once all the clusters are ready, it is necessary to connect them. For now you are using the [containerlab tool](https://containerlab.dev/). Eventually, the inter-cluster networking will be automated as well. +Once all the clusters are ready, it is necessary to connect them. For now you are using the +[Containerlab tool](https://containerlab.dev/). Eventually, the inter-cluster networking will be automated as well. ```bash export E2EDIR=${E2EDIR:-$HOME/test-infra/e2e} @@ -188,7 +191,7 @@ export TESTDIR=${TESTDIR:-$HOME/test-infra/e2e/tests/oai} The output is similar to: -```console +```bash {"workers":["core-md-0-q9mxp-mstdp-6mtvg","edge-md-0-v44mh-pbs9k-t9dq9","regional-md-0-hm5n8-wts7m-5wttp"]} INFO[0000] Containerlab v0.42.0 started INFO[0000] Parsing & checking topology file: clab-topo.gotmpl @@ -234,7 +237,7 @@ kubectl apply -f test-infra/e2e/tests/oai/001-network.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/network created ``` @@ -248,7 +251,7 @@ kubectl apply -f test-infra/e2e/tests/oai/001-secret.yaml The output is similar to: -```console +```bash secret/srl.nokia.com created ``` @@ -262,7 +265,7 @@ The predefined PackageVariant package defines certain resources that exist for t The output is similar to: -```console +```bash rawtopology.topo.nephio.org/nephio created ``` @@ -273,9 +276,9 @@ It might take a couple of seconds for the networks to come up. To list the netwo kubectl get networks.infra.nephio.org ``` -Wait for the the output to be similar as below: +Wait for the output to be similar as below: -```console +```bash NAME READY vpc-cu-e1 True vpc-cudu-f1 True @@ -285,7 +288,8 @@ vpc-ran True ``` -After the networks are successfully configured lets configure metallb ip-address pool for each workload cluster. Some workloads in the workload cluster require metallb to expose their services. +After the networks are successfully configured lets configure MetalLB ip-address pool for each workload cluster. Some +workloads in the workload cluster require MetalLB to expose their services. ```bash @@ -295,7 +299,7 @@ After the networks are successfully configured lets configure metallb ip-address
The output is similar to: -```console +```bash 12:47:00 - INFO: looking for packagerev default/mgmt-staging-7ad404ab9e0e02af747501c6ce9c2c183d02694b using /home/ubuntu/.kube/config 12:47:00 - INFO: found packagerev default/mgmt-staging-7ad404ab9e0e02af747501c6ce9c2c183d02694b using /home/ubuntu/.kube/config [RUNNING] "gcr.io/kpt-fn/search-replace:v0.2" @@ -345,7 +349,7 @@ kubectl apply -f test-infra/e2e/tests/oai/002-operators.yaml The output is similar to: -```console +```bash packagevariantset.config.porch.kpt.dev/oai-common created packagevariant.config.porch.kpt.dev/oai-cp-operators created packagevariant.config.porch.kpt.dev/oai-up-operators created @@ -365,7 +369,7 @@ kubectl get ns --context core-admin@core The output is similar to: -```console +```bash kubectl get ns --context core-admin@core NAME STATUS AGE config-management-monitoring Active 89m @@ -391,7 +395,7 @@ kubectl get pods -n oai-core --context core-admin@core The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE mysql-7dd4cc6945-lqwcv 1/1 Running 0 7m12s ``` @@ -406,7 +410,7 @@ kubectl get pods -n oai-cn-operators --context core-admin@core The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-amf-operator-7cfcfdcf8f-m5b4h 1/1 Running 0 11m oai-ausf-operator-746b56b745-zdfmc 1/1 Running 0 11m @@ -426,7 +430,7 @@ kubectl get ns --context regional-admin@regional The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 98m config-management-system Active 98m @@ -448,7 +452,7 @@ kubectl get ns --context edge-admin@edge The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 98m config-management-system Active 98m @@ -473,7 +477,7 @@ kubectl get pods -n oai-cn-operators --context edge-admin@edge The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-upf-operator-75cbc869cb-67lf9 1/1 Running 0 16m ``` @@ -490,7 +494,7 @@ kubectl create -f test-infra/e2e/tests/oai/003-core-network.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/oai-nrf created packagevariant.config.porch.kpt.dev/oai-udm created packagevariant.config.porch.kpt.dev/oai-ausf created @@ -501,7 +505,7 @@ packagevariant.config.porch.kpt.dev/oai-upf-edge created ``` -All the NFs will wait for NRF to come up and then they will register to NRF. SMF has a dependency on UPF which is described by `dependency.yaml` file in SMF package. It will wait till the time UPF is deployed. It takes around ~800 seconds for the whole core network to come up. NRF is exposing its service via metallb external ip-address. In case metallb ip-address pool is not properly defined in the previous section, then UPF will not be able to register to NRF and in this case SMF and UPF will not be able to communicate. +All the NFs will wait for NRF to come up and then they will register to NRF. SMF has a dependency on UPF which is described by `dependency.yaml` file in SMF package. It will wait till the time UPF is deployed. It takes around ~800 seconds for the whole core network to come up. NRF is exposing its service via MetalLB external ip-address. In case MetalLB ip-address pool is not properly defined in the previous section, then UPF will not be able to register to NRF and in this case SMF and UPF will not be able to communicate. ### Check Core Network Deployment @@ -514,7 +518,7 @@ kubectl get pods -n oai-core --context core-admin@core The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE amf-core-84b5cf67c7-7lzs5 1/1 Running 0 42m ausf-core-7885cb865-pw525 1/1 Running 0 52m @@ -535,7 +539,7 @@ kubectl get pods -n oai-core --context edge-admin@edge The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE upf-edge-55ccb4f9d7-868k6 1/1 Running 0 30m ``` @@ -551,7 +555,7 @@ kubectl logs -n oai-core --context=edge-admin@edge -l workload.nephio.org/oai=up The output is similar to: -```console +```bash * Connection state changed (HTTP/2 confirmed) * Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0 * Using Stream ID: 1 (easy handle 0x622000382900) @@ -586,7 +590,7 @@ kubectl create -f test-infra/e2e/tests/oai/004-ran-network.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/oai-cucp created packagevariant.config.porch.kpt.dev/oai-du created packagevariant.config.porch.kpt.dev/oai-cuup created @@ -605,7 +609,7 @@ kubectl get pods -n oai-ran-cucp --context regional-admin@regional The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-gnb-cu-cp-588f76c5f9-9fp54 1/1 Running 0 10m ``` @@ -617,7 +621,7 @@ kubectl get pods -n oai-ran-cuup --context edge-admin@edge The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-gnb-cu-up-75475f949b-j6chc 1/1 Running 0 9m ``` @@ -629,7 +633,7 @@ kubectl get pods -n oai-ran-du --context edge-admin@edge The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-gnb-du-6cb4cc5fcd-zvlrq 1/1 Running 0 9m ``` @@ -646,7 +650,7 @@ kubectl logs -n oai-ran-cucp --context=regional-admin@regional -l app.kubernetes The output is similar to: -```console +```bash 7792.449954 [NR_RRC] I Accepting new CU-UP ID 3584 name oai-cu-up (assoc_id 8) ``` @@ -659,7 +663,7 @@ kubectl logs -n oai-ran-cucp --context=regional-admin@regional -l app.kubernetes The output is similar to: -```console +```bash 7424.185965 [RRC] I DU uses RRC version 17.3.0 ``` @@ -673,7 +677,7 @@ kubectl logs -n oai-ran-cucp --context=regional-admin@regional -l app.kubernetes The output is similar to: -```console +```bash 9496.571150 [GNB_APP] I [gNB 0] Received NGAP_REGISTER_GNB_CNF: associated AMF 1 ``` @@ -687,7 +691,7 @@ kubectl create -f test-infra/e2e/tests/oai/005-ue.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/oai-ue created ``` @@ -699,7 +703,7 @@ kubectl get pods -n oai-ue --context edge-admin@edge The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE oai-nr-ue-78846cf68c-rxkkz 1/1 Running 0 32m ``` @@ -716,7 +720,7 @@ kubectl logs -n oai-ue $UE_POD -c nr-ue --context edge-admin@edge | grep "Interf The output is similar to: -```console +```bash 24908.869517 [NAS] I [UE] Received REGISTRATION ACCEPT message 24910.122107 [OIP] I Interface oaitun_ue1 successfully configured, ip address 10.2.0.2, mask 255.255.255.0 broadcast address 10.2.0.255 ``` @@ -736,7 +740,7 @@ kubectl exec -it $UE_POD -n oai-ue --context edge-admin@edge -- ping -I oaitun_u The output is similar to: -```console +```bash PING 10.2.0.1 (10.2.0.1) from 10.2.0.2 oaitun_ue1: 56(84) bytes of data. 64 bytes from 10.2.0.1: icmp_seq=1 ttl=64 time=10.9 ms 64 bytes from 10.2.0.1: icmp_seq=2 ttl=64 time=12.1 ms @@ -748,4 +752,4 @@ rtt min/avg/max/mdev = 10.869/11.435/12.093/0.503 ms ``` -For now the extra interfaces which are created using inter-connectivity script does not perform natting to have internet access. +For now the extra interfaces which are created using inter-connectivity script does not perform NAT to have internet access. diff --git a/content/en/docs/guides/user-guides/helm/_index.md b/content/en/docs/guides/user-guides/helm/_index.md index b3c87f3f..d9540b59 100644 --- a/content/en/docs/guides/user-guides/helm/_index.md +++ b/content/en/docs/guides/user-guides/helm/_index.md @@ -7,8 +7,7 @@ weight: 3 ## Overview -Helm integration support in Nephio is currently under investigation -and will progress over the coming releases. +Helm integration support in Nephio is currently under investigation and will progress over the coming releases. Although the direction from Nephio is to encourage the use of [operators](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/) @@ -16,7 +15,7 @@ for deploying on Kubernetes, legacy helm support will be required for a number o ### Deployment options -* [Using Helm To Operator Codegen Sdk](/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md) +* [Using Helm To Operator Codegen SDK](/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md) * [Using Flux CD](/content/en/docs/guides/user-guides/helm/flux-helm.md) * [Operator SDK](https://sdk.operatorframework.io/docs/building-operators/helm/) diff --git a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md index be6735bd..ac3a1a53 100644 --- a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md +++ b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md @@ -25,7 +25,7 @@ defined in the Free5gc Helm chart using a Kubernetes operator. 1. GoLang Version: 1.21 2. Helm : v3.9.3 3. Kubebuilder -4. A Kubernetes Cluster with Calico CNI and multus-cni plugin (Can Refer +4. A Kubernetes Cluster with Calico CNI and Multus CNI plugin (Can Refer [here](https://medium.com/rahasak/deploying-5g-core-network-with-free5gc-kubernets-and-helm-charts-29741cea3922), Before "Deploy Helm-Chart Part" ) 5. Go Packages: @@ -291,12 +291,12 @@ The Generated Go-Code shall contain the following functions: #### A) Pluggable functions -1. CreateAll(): When called, it will create all the k8s resources(services, deployment) on the kubernetes cluster. +1. CreateAll(): When called, it will create all the k8s resources(services, deployment) on the Kubernetes cluster. {{% alert title="Note" color="primary" %}} For your Reconciler to call the function, Replace *YourKindReconciler* with the type of your Reconciler {{% /alert %}} -2. DeleteAll(): When called, it will delete all the k8s resources(services, deployment) on the kubernetes cluster. +2. DeleteAll(): When called, it will delete all the k8s resources(services, deployment) on the Kubernetes cluster. {{% alert title="Note" color="primary" %}} For your Reconciler to call the function, Replace *YourKindReconciler* with the type of your Reconciler {{% /alert %}} @@ -305,15 +305,23 @@ The Generated Go-Code shall contain the following functions: 2. GetDeployment(): Shall return the list of all deployments. & so on #### B) Helper Functions: (For internal use only) -1. deleteMeAfterDeletingUnusedImportedModules: This function is included in the generated Go code to handle the scenario where a module is imported but not used. Once the user has removed the non-required modules from the import statements, they can safely delete this function as well. -2. Pointer Fxns: `intPtr(), int16Ptr(), int32Ptr(), int64Ptr(), boolPtr(), stringPtr()`: Takes the value and returns the pointer to that value. -3. getDataForSecret: This function takes the encodedVal of Secret, decodes it, and returns. -### Step 2: Using kubebuilder to develop the operator +1. *deleteMeAfterDeletingUnusedImportedModules*: This function is included in the generated Go code to handle the + scenario where a module is imported but not used. Once the user has removed the non-required modules from the import + statements, they can safely delete this function as well. +2. Pointer Functions: *intPtr()*, *int16Ptr()*, *int32Ptr()*, *int64Ptr()*, *boolPtr()*, *stringPtr()*: Takes the value + and returns the pointer to that value. +3. *getDataForSecret*: This function takes the *encodedVal* of Secret, decodes it, and returns. + +### Step 2: Using Kubebuilder to develop the operator + Please refer [here](https://book.kubebuilder.io/quick-start) to develop & deploy the operator. -After the basic structure of the operator is created, users can proceed to add their business logic -The `CreateAll()` and `DeleteAll()` functions generated by the SDK can be leveraged for Day-0 resource deployments, allowing users to easily manage the creation and deletion of resources defined in the Helm chart. By integrating their business logic with these functions, users can ensure that their operator effectively handles resource lifecycle management and orchestration within a Kubernetes environment. +After the basic structure of the operator is created, users can proceed to add their business logic. The *CreateAll()* +and *DeleteAll()* functions generated by the SDK can be leveraged for Day-0 resource deployments, allowing users to +manage the creation and deletion of resources defined in the Helm chart. By integrating their business logic with +these functions, users can ensure that their operator effectively handles resource lifecycle management and +orchestration within a Kubernetes environment. In the end, all the resources created could be checked by: `kubectl get pods -n free5gcns` From 6c06b3acb0abd9d37515c12fca89ce767391007a Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 25 Oct 2024 11:51:21 +0300 Subject: [PATCH 45/74] Changes base don Vale suggestions Signed-off-by: Gergely Csatari --- .vale/config/vocabularies/Nephio/accept.txt | 16 +- README.md | 3 +- content/en/docs/apis/_index.md | 9 +- content/en/docs/glossary.md | 8 +- .../unit-testing-mockery.md | 101 ++++--- content/en/docs/guides/user-guides/_index.md | 272 ++++++++---------- .../guides/user-guides/exercise-1-free5gc.md | 89 +++--- content/en/docs/porch/_index.md | 8 +- .../docs/porch/contributors-guide/_index.md | 14 +- .../porch/contributors-guide/dev-process.md | 17 +- .../environment-setup-vm.md | 32 +-- .../contributors-guide/environment-setup.md | 12 +- .../en/docs/porch/package-orchestration.md | 5 +- content/en/docs/porch/package-variant.md | 4 +- .../porch/running-porch/running-on-GKE.md | 10 +- .../adding-external-git-ca-bundle.md | 8 +- .../using-porch/install-and-using-porch.md | 76 ++--- .../porch/using-porch/porchctl-cli-guide.md | 5 +- .../porch/using-porch/usage-porch-kpt-cli.md | 10 +- content/en/docs/release-notes/R3.md | 2 +- 20 files changed, 356 insertions(+), 345 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 8fc0a143..2f0c64a9 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -13,6 +13,9 @@ Codegen [Cc]loudified Containerlab CLI +CR +CRs +CRs CRD CRDs Crossplane @@ -26,6 +29,9 @@ GitHub GitLab GitOps Graphviz +GRPC +GVK +GVKs [Hh]ostname [Hh]omebrew html @@ -38,6 +44,7 @@ kubelet Kubernetes Kustomize Libvirt +MacBook MetalLB [Nn]amespace Nephio @@ -50,6 +57,7 @@ NFs Multus [Mm]ultivendor [Mm]ulticloud +Nginx OAuth OCI [Oo]nboarding @@ -59,6 +67,7 @@ Okta parameterRef passwordless [Pp]kgserver +Podman [Pp]orch [Pp]orchctl Postgres @@ -73,6 +82,9 @@ TLS [Tt]riage [Tt]ko [Tt]oolchain +UI +UIs +URI URIs [Uu]ntar vCPU @@ -85,6 +97,8 @@ VS Code vSphere WebUI xApps +YAML # Nephio contributors mentioned in the docs -Tal Liron \ No newline at end of file +Tal +Liron \ No newline at end of file diff --git a/README.md b/README.md index 8d59d017..71e23598 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,8 @@ The documentation is served from [docs.nephio.org](https://docs.nephio.org/) and ## Status of the documentation -In R2 release, a Hugo / Docsy based documentation site was introduced for the Nephio documentation. Hugo / Docsy uses the Markdown files hosted in the Github repo to generate the documentation website. We are still working on the restructuring the content and finalizing the look and feel of the website. +In R2 release, a Hugo / Docsy based documentation site was introduced for the Nephio documentation. Hugo / Docsy uses +the Markdown files hosted in the GitHub repo to generate the documentation website. ## How to contribute to the documentation diff --git a/content/en/docs/apis/_index.md b/content/en/docs/apis/_index.md index 70dffa44..5c6cc7bf 100644 --- a/content/en/docs/apis/_index.md +++ b/content/en/docs/apis/_index.md @@ -14,12 +14,15 @@ relationships, and is based on an [original document](https://docs.google.com/document/d/1-5nlpY4FbuhWtdKTvIqPOv4bWmA6zx6TdHoEfk9Jc_Q/edit) developed by Tal Liron. -The aim is to keep these diagrams as simple as possible for now and only convey the important aspects of the modelled entities. As such they are intended to give a high-level overview of the entities and relationships that can be accessed and modified via the Nephio API, and provide reference to detailed documentation, generated from the code, where available. - +The aim is to keep these diagrams as simple as possible for now and only convey the important aspects of the modelled +entities. As such they are intended to give a high-level overview of the entities and relationships that can be accessed +and modified via the Nephio API, and provide reference to detailed documentation, generated from the code, where +available. ## Topology and Network APIs -This is a high-level overview of the Nephio models and their relationships, with links to the relevant API documentation where available, and to the source code where not. +This is a high-level overview of the Nephio models and their relationships, with links to the relevant API documentation +where available, and to the source code where not. ```mermaid flowchart TD diff --git a/content/en/docs/glossary.md b/content/en/docs/glossary.md index ad219e63..318f3dc4 100644 --- a/content/en/docs/glossary.md +++ b/content/en/docs/glossary.md @@ -5,7 +5,7 @@ weight: 4 --- We use many terms in our Nephio discussions, coming from different domains -including telco, Kubernetes, configuration management, and our own +including telecom, Kubernetes, configuration management, and our own Nephio-specific terms. This glossary is intended to help clarify our usage of these terms. @@ -141,7 +141,7 @@ Day 2 and beyond, all of which are challenges with current techniques. Hydration may be *out-of-place*, where the source material (e.g., the Helm chart), is separate from the output of the hydration process (the manifests). This is probably the most familiar type of hydration, used by Helm and -kustomize, for example. Think of it as a pipeline with an input artifact, input +Kustomize, for example. Think of it as a pipeline with an input artifact, input values, and output artifacts. Hydration may also be *in-place*, where modifications are directly written to @@ -159,7 +159,7 @@ outcomes achievable. This leads to "over-parameterization" - where effectively every option possible in the outputs becomes an option in the input. At that point, you have mostly *moved* complexity rather than *reduced* complexity. In-place hydration can help with the over-parameterization, as values that are -rarely changed by users can simply be edited in-place. +rarely changed by users can be edited in-place. While related, *DRY* and *WET* are not exactly the same concepts as *in-place* and *out-of-place* hydration. The former two refer to principles, whereas the latter @@ -218,7 +218,7 @@ with KRM on the input and output, rather than simple streams. Generally, best practices suggest KRM functions be hermetic (that is, they do not access the outside world). -In terms of the specification linked above, kustomize, kpt, and Porch are all +In terms of the specification linked above, Kustomize, kpt, and Porch are all *orchestrators*. *See also*: [Controller](#controller), [kpt](#kpt), [Porch](#porch) diff --git a/content/en/docs/guides/contributor-guides/unit-testing-mockery.md b/content/en/docs/guides/contributor-guides/unit-testing-mockery.md index 8f745362..02459e80 100644 --- a/content/en/docs/guides/contributor-guides/unit-testing-mockery.md +++ b/content/en/docs/guides/contributor-guides/unit-testing-mockery.md @@ -5,18 +5,22 @@ description: > weight: 5 --- -This guide describes how to use [testify](https://pkg.go.dev/github.com/stretchr/testify) and [mockery](https://vektra.github.io/mockery/latest/) for writing, mocking, and executing unit tests. -This guide will help folks come up to speed on using testify and mockery. +This guide describes how to use [testify](https://pkg.go.dev/github.com/stretchr/testify) and +[mockery](https://vektra.github.io/mockery/latest/) for writing, mocking, and executing unit tests. This guide will help +folks come up to speed on using testify and mockery. ## How Mockery works -The [mockery documentation](https://vektra.github.io/mockery/latest/#why-mockery) describes why you would use and how to use Mockery. In a nutshell, Mockery generates mock implementations for interfaces in `go`, which you can then use instead of real implementations when unit testing. +The [mockery documentation](https://vektra.github.io/mockery/latest/#why-mockery) describes why you would use and how to +use Mockery. In a nutshell, Mockery generates mock implementations for interfaces in `go`, which you can then use +instead of real implementations when unit testing. ## Mockery support in Nephio `make` -The `make` files in Nephio repos containing `go` code have targets to support mockery. +The `make` files in Nephio repositories containing `go` code have targets to support mockery. -The [default-mockery.mk](https://github.com/nephio-project/nephio/blob/main/default-mockery.mk) file in the root of Nephio repos is included in Nephio `make` runs. +The [default-mockery.mk](https://github.com/nephio-project/nephio/blob/main/default-mockery.mk) file in the root of +Nephio repository is included in Nephio `make` runs. There are two targets in default-mockery.mk: @@ -25,47 +29,60 @@ There are two targets in default-mockery.mk: The targets above must be run explicitly. -Run `make install-mockery` to install mockery in your container runtime (docker, podman etc) or locally if you have no container runtime running. You need only run this target once unless you need to reinstall Mockery for whatever reason. +Run `make install-mockery` to install mockery in your container runtime (Docker, Podman etc) or locally if you have no +container runtime running. You need only run this target once unless you need to reinstall Mockery for whatever reason. -Run `make generate-mocks` to generate the mocked implementation of the go interfaces specified in '.mockery.yaml' files. You need to run this target each time an interface that you are mocking changes or whenever you change the contents of a `.mockery.yaml` file. You can run `make generate-mocks` in the repo root to generate or re-generate all interfaces or in subdirectories containing a `Makefile` to generate or regenerate only the interfaces in that subdirectory and its children. +Run `make generate-mocks` to generate the mocked implementation of the go interfaces specified in '.mockery.yaml' files. +You need to run this target each time an interface that you are mocking changes or whenever you change the contents of a +`.mockery.yaml` file. You can run `make generate-mocks` in the repo root to generate or re-generate all interfaces or in +subdirectories containing a `Makefile` to generate or regenerate only the interfaces in that subdirectory and its +children. -The generate-mocks target looks for `.mockery.yaml` files in the repo and it runs the mockery mock generator on each `.mockery.yaml` file it finds. This has the nice effect of allowing `.mockery.yaml` files to be in either the root of the repo or in subdirectories, so the choice of placement of `.mockery.yaml` files is left to the developer. +The generate-mocks target looks for `.mockery.yaml` files in the repo and it runs the mockery mock generator on each +`.mockery.yaml` file it finds. This has the nice effect of allowing `.mockery.yaml` files to be in either the root of +the repo or in subdirectories, so the choice of placement of `.mockery.yaml` files is left to the developer. ## The .mockery.yaml file -The `.mockery.yaml` file specifies which mock implementations Mockery should generate and also controls how that generation is performed. Here we just give an overview of `mockery.yaml`. For full details consult the [configuration](https://github.com/vektra/mockery/blob/master/docs/configuration.md) section of the Mockery documentation. +The `.mockery.yaml` file specifies which mock implementations Mockery should generate and also controls how that +generation is performed. Here we just give an overview of `mockery.yaml`. For full details consult the +[configuration](https://github.com/vektra/mockery/blob/master/docs/configuration.md) section of the Mockery +documentation. ### Example 1 -Here, we use the [Nephio Controllers package .mockery.yaml](https://github.com/nephio-project/nephio/blob/main/controllers/pkg/.mockery.yaml) file as an example: +Here, we use the +[Nephio Controllers package .mockery.yaml](https://github.com/nephio-project/nephio/blob/main/controllers/pkg/.mockery.yaml) file as an example: -``` +```go 1. packages: 2. github.com/nephio-project/nephio/controllers/pkg/giteaclient: ``` -We provide a list of the packages for which we want to generate mocks. In this example, we only have one package. Here we want to generate mocks for the GiteaClient interface so we provide the package path to the interface. +We provide a list of the packages for which we want to generate mocks. In this example, we only have one package. Here +we want to generate mocks for the GiteaClient interface so we provide the package path to the interface. -``` +```go 3. interfaces: 4. GiteaClient: 5. config: 6. dir: "{{.InterfaceDir}}" ``` -We want mocks to be generated for the `GiteaClient` go interface (line 4). The `{{.InterfaceDir}}` parameter (line 6) asks Mockery to generate the mock file in the same directory as the interface is located. +We want mocks to be generated for the `GiteaClient` go interface (line 4). The `{{.InterfaceDir}}` parameter (line 6) +asks Mockery to generate the mock file in the same directory as the interface is located. ### Example 2 This example is a slightly more evolved version of the file used in Example 1 above. -``` +```go 1. with-expecter: true ``` Generate EXPECT() methods for your mocks, see the [configuration](https://github.com/vektra/mockery/blob/master/docs/configuration.md) section of the Mockery documentation. -``` +```go 2. packages: 3. github.com/nephio-project/nephio/controllers/pkg/giteaclient: 4. interfaces: @@ -76,20 +93,21 @@ Generate EXPECT() methods for your mocks, see the [configuration](https://github Lines 2 to 7 are as explained in Example 1 above. -``` +```go 8. sigs.k8s.io/controller-runtime/pkg/client: ``` Generate mocks for the external package `sigs.k8s.io/controller-runtime/pkg/client`. -``` +```go 9. interfaces: 10. Client: ``` -Generate a mock implementation of the go interface `Client` in the external package `sigs.k8s.io/controller-runtime/pkg/client`. +Generate a mock implementation of the go interface `Client` in the external package +`sigs.k8s.io/controller-runtime/pkg/client`. -``` +```go 11. config: 12. dir: "mocks/external/{{ .InterfaceName | lower }}" 13. outpkg: "mocks" @@ -101,15 +119,18 @@ Create the mocks for the `Client` interface in the `mocks/external/client` direc [This mocked implementation of the GiteaClient interface](https://github.com/nephio-project/nephio/blob/main/controllers/pkg/giteaclient/mock_GiteaClient.go) was generated by mockery using the `make generate-mocks` make target. -We can treat this generated file as a black box and we do not have to know the details of the contents of this file to write unit tests. +We can treat this generated file as a black box and we do not have to know the details of the contents of this file to +write unit tests. ## The Mockery Utils package -The [mockery utils](https://github.com/nephio-project/nephio/tree/main/testing/mockeryutils) package is a utility package that you can use to initialize your mocks and to define some common fields for your tests. +The [mockery utils](https://github.com/nephio-project/nephio/tree/main/testing/mockeryutils) package is a utility +package that you can use to initialize your mocks and to define some common fields for your tests. -[mockeryutils-types.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the `MockHelper` struct, which allows you to control the behaviour of a mock. +[mockeryutils-types.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) +contains the `MockHelper` struct, which allows you to control the behaviour of a mock. -``` +```go type MockHelper struct { MethodName string // The mocked method name for which we want to supply configuration ArgType []string // The arguments we are supplying to the mocked method @@ -117,11 +138,13 @@ type MockHelper struct { } ``` -The `MockHelper` struct is used to configure a mocked method to expect and return a certain set of arguments. We pass instances of this struct to the mocked interface during tests. +The `MockHelper` struct is used to configure a mocked method to expect and return a certain set of arguments. We pass +instances of this struct to the mocked interface during tests. -[mockeryutils.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the `InitMocks` function, which initializes your mocks for you before a test. +[mockeryutils.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) +contains the `InitMocks` function, which initializes your mocks for you before a test. -``` +```go func InitMocks(mocked *mock.Mock, mocks []MockHelper) ``` @@ -131,7 +154,7 @@ For the given `mocked` interface, the function initializes the `mocks` as specif The unit tests for the [Repository Reconciler](https://github.com/nephio-project/nephio/blob/main/controllers/pkg/reconcilers/repository/reconciler_test.go) use the mocks generated above. -``` +```go type fields struct { APIPatchingApplicator resource.APIPatchingApplicator giteaClient giteaclient.GiteaClient @@ -151,21 +174,22 @@ type repoTest struct { wantErr bool } ``` -The code above allows us to specify input data and the expected outcome for tests. Each test is specified as an instance of the `repoTest` struct. For each test, we specify its fields and arguments, and specify the mocking for the test. +The code above allows us to specify input data and the expected outcome for tests. Each test is specified as an instance +of the `repoTest` struct. For each test, we specify its fields and arguments, and specify the mocking for the test. -``` +```go func TestUpsertRepo(t *testing.T) ``` This method contains unit tests for the upsertRepo method written using mockery and testify. -``` +```go tests := []repoTest{} ``` This is the specification of an array of tests that we will run. -``` +```go { name: "Create repo: cr fields not blank", fields: fields{resource.NewAPIPatchingApplicator(nil), nil, nil, log.FromContext(context.Background())}, @@ -194,9 +218,13 @@ This is the specification of an array of tests that we will run. } ``` -The code above specifies a single test and is an instance of the `tests` array. We specify the fields, arguments, and mocks for the test. In this case, we mock three functions on our GiteaClient interface: `GetMyUserInfo`, `GetRepo`, and `CreateRepo`. We specify the arguments we expect for each function and specify what the function should return if it receives correct arguments. Of course, if the mocked function receives incorrect arguments, it will report an error. The `wantErr` value indicates if we expect the `upsertRepo` function being tested to succeed or fail. +The code above specifies a single test and is an instance of the `tests` array. We specify the fields, arguments, and +mocks for the test. In this case, we mock three functions on our GiteaClient interface: `GetMyUserInfo`, `GetRepo`, and +`CreateRepo`. We specify the arguments we expect for each function and specify what the function should return if it +receives correct arguments. If the mocked function receives incorrect arguments, it will report an error. The +`wantErr` value indicates if we expect the `upsertRepo` function being tested to succeed or fail. -``` +```go for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { r := &reconciler{ @@ -214,9 +242,10 @@ for _, tt := range tests { } ``` -The code above executes the tests. We run a reconciler `r` and initialize our tests using the local `initMockeryTests()` function. We then call the `upsertRepo` function to test it and check the result. +The code above executes the tests. We run a reconciler `r` and initialize our tests using the local `initMockeryTests()` +function. We then call the `upsertRepo` function to test it and check the result. -``` +```go func initMockeryMocks(tt *repoTest) { mockGClient := new(giteaclient.MockGiteaClient) tt.args.giteaClient = mockGClient diff --git a/content/en/docs/guides/user-guides/_index.md b/content/en/docs/guides/user-guides/_index.md index 2978cbe0..d6eb267f 100644 --- a/content/en/docs/guides/user-guides/_index.md +++ b/content/en/docs/guides/user-guides/_index.md @@ -7,46 +7,38 @@ weight: 2 ## Overview -Nephio is a Kubernetes-based intent-driven automation of network functions and -the underlying infrastructure that supports those functions. It allows users to -express high-level intent, provides intelligent, declarative automation that -can set up the cloud and edge infrastructure, renders initial configurations for -the network functions, and then delivers those configurations to the right -clusters to get the network up and running. - -Technologies like distributed cloud enable on-demand, API-driven access to the -edge. Unfortunately, existing brittle, imperative, fire-and-forget orchestration -methods struggle to take full advantage of the dynamic capabilities of these new -infrastructure platforms. To succeed at this, Nephio uses new approaches that -can handle the complexity of provisioning and managing a multi-vendor, -multi-site deployment of interconnected network functions across on-demand +Nephio is a Kubernetes-based intent-driven automation of network functions and the underlying infrastructure that +supports those functions. It allows users to express high-level intent, provides intelligent, declarative automation +that can set up the cloud and edge infrastructure, renders initial configurations for the network functions, and then +delivers those configurations to the right clusters to get the network up and running. + +Technologies like distributed cloud enable on-demand, API-driven access to the edge. Unfortunately, existing brittle, +imperative, fire-and-forget orchestration methods struggle to take full advantage of the dynamic capabilities of these +new infrastructure platforms. To succeed at this, Nephio uses new approaches that can handle the complexity of +provisioning and managing a multi-vendor, multi-site deployment of interconnected network functions across on-demand distributed cloud. -The solution is intended to address the initial provisioning of the network -functions and the underlying cloud infrastructure, and also provide -Kubernetes-enabled reconciliation to ensure the network stays up through -failures, scaling events, and changes to the distributed cloud. +The solution is intended to address the initial provisioning of the network functions and the underlying cloud +infrastructure, and also provide Kubernetes-enabled reconciliation to ensure the network stays up through failures, +scaling events, and changes to the distributed cloud. Nephio breaks down the larger problem into two primary areas: -* Kubernetes as a uniform automation control plane in each site to configure all - aspects of the distributed cloud and network functions -* An automation framework that leverages Kubernetes declarative, - actively-reconciled methodology along with machine-manipulable configuration - to tame the complexity of these configurations. +* Kubernetes as a uniform automation control plane in each site to configure all aspects of the distributed cloud and + network functions +* An automation framework that leverages Kubernetes declarative, actively-reconciled methodology along with + machine-manipulable configuration to tame the complexity of these configurations. ### Kubernetes as a Uniform Automation Control Plane -Utilizing Kubernetes as the automation control plane at each layer of the stack -simplifies the overall automation and enables declarative management with active -reconciliation for the entire stack. We can broadly think of three layers in the -stack, as shown below. +Utilizing Kubernetes as the automation control plane at each layer of the stack simplifies the overall automation and +enables declarative management with active reconciliation for the entire stack. We can broadly think of three layers in +the stack, as shown below. * Cloud infrastructure * Workload (network function) resources * Workload (network function) configuration -Nephio is establishing open, extensible Kubernetes Custom Resource Definition -(CRD) models for each layer of the stack, in conformance to the 3GPP & O-RAN -standards. +Nephio is establishing open, extendable Kubernetes Custom Resource Definition (CRD) models for each layer of the stack, +in conformance to the 3GPP & O-RAN standards. ![nephio-overview.png](/static/images/user-guides/nephio-overview.png) @@ -54,56 +46,43 @@ standards. ### Custom Resources and Controllers -A Custom Resource Definition (CRD) is an extension mechanism for adding custom -data types to Kubernetes. The CRDs are the schemas - analogous to table -definitions in a relational database, for example. The instances of those - -analogous to rows in a RDBMS - are called Custom Resources or CRs. People often -accidentally say "CRDs" when they mean "CRs", so be sure to ask for -clarification if the context doesn't make it clear which is meant. - -In Kubernetes, resources - built-in ones as well as CRs - are processed by -controllers. A controller actuates the resource. For example, K8s actuates a -Service with Type LoadBalancer by creating a cloud provider load balancer -instance. Since Kubernetes is declarative, it doesn't just actuate once. -Instead, it actively reconciles the intent declared in the resource, with the -actual state of the managed entity. If the state of the entity changes (a Pod is -destroyed), Kubernetes will modify or recreate the entity to match the desired -state. And of course if the intended state changes, Kubernetes will actuate the -new intention. Speaking precisely, a controller manages one or a few very -closely related types of resources. A controller manager is single binary that -embeds multiple controllers, and an operator is a set of these that manages a -particular type of workload. Speaking loosely, controller and operator are often -used interchangeably, though an operator always refers to code managing CRs -rather than Kubernetes built-in types. - -All Kubernetes resources have a metadata field that contains the name, namespace -(if not cluster scoped), annotations and labels for the resource. Most resources -also have a spec and a status field. The spec field holds the intended state, -and the status field holds the observed state and any control data needed by the -controller to do its job. Typically, controllers read the spec and write the -status. +A Custom Resource Definition (CRD) is an extension mechanism for adding custom data types to Kubernetes. The CRDs are +the schemas - analogous to table definitions in a relational database, for example. The instances of those - analogous +to rows in a RDBMS - are called Custom Resources or CRs. People often accidentally say "CRDs" when they mean "CRs", so +be sure to ask for clarification if the context doesn't make it clear which is meant. + +In Kubernetes, resources - built-in ones as well as CRs - are processed by controllers. A controller actuates the +resource. For example, K8s actuates a Service with Type LoadBalancer by creating a cloud provider load balancer +instance. Since Kubernetes is declarative, it doesn't just actuate once. Instead, it actively reconciles the intent +declared in the resource, with the actual state of the managed entity. If the state of the entity changes (a Pod is +destroyed), Kubernetes will modify or recreate the entity to match the desired state. And if the intended state changes, +Kubernetes will actuate the new intention. Speaking precisely, a controller manages one or a few closely related types +of resources. A controller manager is single binary that embeds multiple controllers, and an operator is a set of these +that manages a particular type of workload. Speaking loosely, controller and operator are often used interchangeably, +though an operator always refers to code managing CRs rather than Kubernetes built-in types. + +All Kubernetes resources have a metadata field that contains the name, namespace (if not cluster scoped), annotations +and labels for the resource. Most resources also have a spec and a status field. The spec field holds the intended +state, and the status field holds the observed state and any control data needed by the controller to do its job. +Typically, controllers read the spec and write the status. ### Kpt -Kpt is a GitOps based package management tool for Kubernetes. It uses -configuration-as-data principle. For more details refer to [Kpt -book](https://kpt.dev/book/). +Kpt is a GitOps based package management tool for Kubernetes. It uses configuration-as-data principle. For more details +refer to [Kpt book](https://kpt.dev/book/). ### Porch -[Package Orchestration service](https://kpt.dev/book/08-package-orchestration/) -(Porch) enables workflows similar to those supported by the kpt CLI, but makes -them available as a Kubernetes service. For more details refer to [Porch user -guide](https://kpt.dev/guides/porch-user-guide). +[Package Orchestration service](https://kpt.dev/book/08-package-orchestration/) (Porch) enables workflows similar to +those supported by the kpt CLI, but makes them available as a Kubernetes service. For more details refer to +[Porch user guide](https://kpt.dev/guides/porch-user-guide). ### ConfigSync -Config Sync lets cluster operators and platform administrators deploy consistent -configurations and policies. You can deploy these configurations and policies to -individual Kubernetes clusters, multiple clusters that can span hybrid and -multi-cloud environments, and multiple namespaces within clusters. This process -simplifies and automates configuration and policy management at scale. Config -Sync also lets development teams independently manage their namespaces within +Config Sync lets cluster operators and platform administrators deploy consistent configurations and policies. You can +deploy these configurations and policies to individual Kubernetes clusters, multiple clusters that can span hybrid and +multi-cloud environments, and multiple namespaces within clusters. This process simplifies and automates configuration +and policy management at scale. Config Sync also lets development teams independently manage their namespaces within clusters, while still being subject to policy guardrails set by administrators. Config Sync is an open-source project and the source and releases available @@ -111,85 +90,66 @@ Config Sync is an open-source project and the source and releases available ### Packages -Packages or Kpt Packages are bundles of Kubernetes resource files, along with a -Kptfile (also in Kubernetes Resource Model (KRM) format). They provide the basic -unit of management in the Kpt toolchain. This toolchain is used to manage the -configuration before it reaches the Kubernetes API server. This "shift left" -model is critical to allowing safe collaborative, automated configuration -creation and editing, because errors or partial configurations can be resolved +Packages or Kpt Packages are bundles of Kubernetes resource files, along with a Kptfile (also in Kubernetes Resource +Model (KRM) format). They provide the basic unit of management in the Kpt toolchain. This toolchain is used to manage +the configuration before it reaches the Kubernetes API server. This "shift left" model is critical to allowing safe +collaborative, automated configuration creation and editing, because errors or partial configurations can be resolved prior to affecting operations. -Following the configuration-as-data principle, the package is not encapsulated. -Since the contents of the package is simply KRM resources, independently -designed tools and automations can operate on those resources. Instead of an -encapsulated abstract interface where inputs are provided and manifests are -rendered, we have an open concept we refer to as "the package is the interface". - -In order to allow multiple actors to operate on that open package safely, we -mediate the process via an API layer called Porch (for "Package Orchestration"). -Porch provides a Kubernetes API for manipulating packages, their contents, and -how they map to repositories (which may be Git or OCI repositories). - -In Porch, packages always live within a repository. A package may have many -package revisions, or versions of the package, within the same repository. A -draft package revision lives in a draft branch, not in the main branch. When a -draft is ready to be used, it may be proposed for publication. If the proposed -draft is approved it becomes a published revision, and is assigned a revision -number by Porch. Published packages are tagged in the underlying repository. A -given package can have many revisions, but they are all sequentially ordered as -"v1", "v2", "v3", etc. This version is the revision number of the configuration -package, not the underlying software contained in the package. This simple -sequential numbering makes it easier to do automatic discovery of configuration -package updates. - -There are a few different techniques we have for manipulating the content of -packages. The simplest and most basic is to just edit the files. Since the -"package is the interface", it is perfectly fine to simply edit files within the -package directly, and save them. The fact that the package is all KRM data makes -it relatively easy to merge upstream changes with downstream changes. - -The next simplest is with KRM functions, also known as kpt functions. These are -small pieces of reusable code that perform a single purpose in manipulating the -configuration. When executed, a KRM function typically is provided with all the -resources in the package, and modifies them however it needs to, and then emits -the updated list as output. A KRM function can be called imperatively, by simply -executing it against the package. This can be used, for example, with the -search-and-replace function to do a one-time change across many resources in a -package. Or, a KRM function can be setup in the Kptfile to be called -declaratively; it will be called every time Porch saves the package. This is -useful for functions that want to make sure information is consistent across -several resources within a package. For example, the set-namespace function can -be used to ensure the namespace is set correctly across all resources in a +Following the configuration-as-data principle, the package is not encapsulated. Since the contents of the package is +KRM resources, independently designed tools and automations can operate on those resources. Instead of an encapsulated +abstract interface where inputs are provided and manifests are rendered, we have an open concept we refer to as +"the package is the interface". + +In order to allow multiple actors to operate on that open package safely, we mediate the process via an API layer called +Porch (for "Package Orchestration"). Porch provides a Kubernetes API for manipulating packages, their contents, and how +they map to repositories (which may be Git or OCI repositories). + +In Porch, packages always live within a repository. A package may have many package revisions, or versions of the +package, within the same repository. A draft package revision lives in a draft branch, not in the main branch. When a +draft is ready to be used, it may be proposed for publication. If the proposed draft is approved it becomes a published +revision, and is assigned a revision number by Porch. Published packages are tagged in the underlying repository. A +given package can have many revisions, but they are all sequentially ordered as "v1", "v2", "v3", etc. This version is +the revision number of the configuration package, not the underlying software contained in the package. This sequential +numbering makes it easier to do automatic discovery of configuration package updates. + +There are a few different techniques we have for manipulating the content of packages. The simplest and most basic is to +just edit the files. Since the "package is the interface", it is perfectly fine to edit files within the package +directly, and save them. The fact that the package is all KRM data makes it relatively easy to merge upstream changes +with downstream changes. + +The next simplest is with KRM functions, also known as kpt functions. These are small pieces of reusable code that +perform a single purpose in manipulating the configuration. When executed, a KRM function typically is provided with all +the resources in the package, and modifies them however it needs to, and then emits the updated list as output. A KRM +function can be called imperatively, by running it against the package. This can be used, for example, with the +search-and-replace function to do a one-time change across many resources in a package. Or, a KRM function can be setup +in the Kptfile to be called in a declarative manner; it will be called every time Porch saves the package. This is +useful for functions that want to make sure information is consistent across several resources within a package. For +example, the set-namespace function can be used to ensure the namespace is set correctly across all resources in a package, even if a new resource is added later. -Functions are intended to be simple, and hermetic. This means they do not reach -out to other systems to gather information. They do not have network access nor -can they mount volumes. Instead, they simply take the inputs provided in the +Functions are intended to be simple, and hermetic. This means they do not reach out to other systems to gather +information. They do not have network access nor can they mount volumes. Instead, they take the inputs provided in the package resources, and modify or generate other resources based on those. -Sometimes in order to create a re-usable function, that function will need -inputs. For simpler functions, inputs are captured via ConfigMap resources -within the Kptfile directly. For more complex function inputs, a -function-specific custom resource can be used. These resources though only live -within the package; we do not want them actually pushed to the cluster when we -deploy the package. To avoid that, we add a special annotation on the resources, -config.kubernetes.io/local-config: "true". We thus often refer to these types of -resources as "local config" resources. +Sometimes in order to create a re-usable function, that function will need inputs. For simpler functions, inputs are +captured via ConfigMap resources within the Kptfile directly. For more complex function inputs, a function-specific +custom resource can be used. These resources though only live within the package; we do not want them actually pushed to +the cluster when we deploy the package. To avoid that, we add a special annotation on the resources, +config.kubernetes.io/local-config: "true". We thus often refer to these types of resources as "local config" resources. -Stepping up the power and complexity level, the fact that Porch is a Kubernetes -API service means that we can build Kubernetes controllers on top of it. This is -exactly what we are doing in Nephio. +Stepping up the power and complexity level, the fact that Porch is a Kubernetes API service means that we can build +Kubernetes controllers on top of it. This is exactly what we are doing in Nephio. ### Package Ancestry -A package may have a single upstream parent, and many downstream descendants. -The Kptfiles in these packages are used to maintain the relationships, capturing -ancestry relationships like those shown below. +A package may have a single upstream parent, and many downstream descendants. The Kptfiles in these packages are used to +maintain the relationships, capturing ancestry relationships like those shown below. ![package-ancestry.png](/static/images/user-guides/package-ancestry.png) -By tracking these relationships, changes at the original source can be -propagated via controlled automation down the tree. +By tracking these relationships, changes at the original source can be propagated via controlled automation down the +tree. ### Package Configuration Journey @@ -199,9 +159,8 @@ propagated via controlled automation down the tree. ### API -CRDs provided for UPF, SMF and AMF 5g core services -Specialization CRDs provided for integrating with IP address and VLAN allocation -backends. +CRDs provided for UPF, SMF and AMF 5g core services Specialization CRDs provided for integrating with IP address and +VLAN allocation backends. ### Web UI @@ -216,27 +175,22 @@ Basic web UI to view and manage Package Variants and Package variant sets. ### Functionalities -* Create Kubernetes clusters. This functionality is based on [cluster - API](https://cluster-api.sigs.k8s.io/). At this time only - [KIND](https://kind.sigs.k8s.io/) clusters creation is supported. -* Fully automated deployment of UPF, SMF and AMF services of - [free5Gc](https://free5gc.org/) . These are deployed on multiple clusters - based on user's intent expressed via CRDs. +* Create Kubernetes clusters. This functionality is based on [cluster API](https://cluster-api.sigs.k8s.io/). At this + time only [kind](https://kind.sigs.k8s.io/) clusters creation is supported. +* Fully automated deployment of UPF, SMF and AMF services of [Free5Gc](https://free5gc.org/) . These are deployed on + multiple clusters based on user's intent expressed via CRDs. * Inter cluster networking setup. -* Deployment of other free5gc functions. Some manual configuration such as IP - addresses may be needed for these services. -* Auto-scale up of UPF, SMF and AMF services based on changes to capacity - requirements expressed as user intent. +* Deployment of other free5gc functions. Some manual configuration such as IP addresses may be needed for these + services. +* Auto-scale up of UPF, SMF and AMF services based on changes to capacity requirements expressed as user intent. ## Deployment model For the purposes of Nephio deployment, we can categorize clusters into two varieties: -- Management cluster: This is where the majority of Nephio components are - installed. It is dedicated to manage the deployment and lifecycle management - of network functions that will be deployed on workload clusters. -- Workload cluster: This is where the actual network function workloads are - deployed and running. +- Management cluster: This is where the majority of Nephio components are installed. It is dedicated to manage the + deployment and lifecycle management of network functions that will be deployed on workload clusters. +- Workload cluster: This is where the actual network function workloads are deployed and running. The diagram below depicts deployment at the high level. @@ -250,7 +204,7 @@ The diagram below depicts deployment at the high level. #### Nephio Controllers * Nephio Controller Operator -* Vlan and IPAM Controller +* VLAN and IPAM Controller * Cluster API Infrastructure controller * Status Aggregator @@ -277,8 +231,8 @@ The diagram below depicts deployment at the high level. * Watcher agent #### Workloads -* Workload operators (eg: free5gc operator) -* Workload controllers (eg: free5gc smf/upf/amf controllers) +* Workload operators (e.g.: Free5gc operator) +* Workload controllers (e.g.: Free5gc smf/upf/amf controllers) ## General Workflow @@ -328,8 +282,8 @@ The diagram below depicts deployment at the high level. ## Troubleshooting and Workarounds -On the demo VM, the `test-infra/e2e/provision/hacks` directory contains some -workaround scripts. Also, please see the Release Notes [known issues](/content/en/docs/release-notes/R2.md#known-issues-and-workarounds). +On the demo VM, the `test-infra/e2e/provision/hacks` directory contains some workaround scripts. Also, please see the +Release Notes [known issues](/content/en/docs/release-notes/R2.md#known-issues-and-workarounds). ## Next Steps diff --git a/content/en/docs/guides/user-guides/exercise-1-free5gc.md b/content/en/docs/guides/user-guides/exercise-1-free5gc.md index 8025bcb9..a71f28c8 100644 --- a/content/en/docs/guides/user-guides/exercise-1-free5gc.md +++ b/content/en/docs/guides/user-guides/exercise-1-free5gc.md @@ -60,7 +60,7 @@ Use the session just started on the VM to run these commands: {{% alert title="Note" color="primary" %}} After fresh `docker` install, verify `docker` supplementary group is loaded by executing `id | grep docker`. -If not, logout and login to the VM or execute the `newgrp docker` to ensure the `docker` supplementary group is loaded. +If not, logout and login to the VM or run `newgrp docker` to ensure the `docker` supplementary group is loaded. {{% /alert %}} @@ -71,7 +71,7 @@ kubectl get repositories The output is similar to: -```console +```bash NAME TYPE CONTENT DEPLOYMENT READY ADDRESS catalog-distros-sandbox git Package false True https://github.com/nephio-project/catalog.git catalog-infra-capi git Package false True https://github.com/nephio-project/catalog.git @@ -100,7 +100,7 @@ porchctl rpkg get --name nephio-workload-cluster The output is similar to: -```console +```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY catalog-infra-capi-d4d7d55835a5578f5c43fc8244deb6a091a8643f nephio-workload-cluster main main false Published catalog-infra-capi catalog-infra-capi-b0ae9512aab3de73bbae623a3b554ade57e15596 nephio-workload-cluster v2.0.0 v2.0.0 true Published catalog-infra-capi @@ -117,7 +117,7 @@ porchctl rpkg clone -n default catalog-infra-capi-b0ae9512aab3de73bbae623a3b554a The output is similar to: -```console +```bash mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 created ``` @@ -132,8 +132,8 @@ To pull the package to a local directory, use the `rpkg pull` command: porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional ``` -The package is now in the `regional` directory. So you can execute the `set-labels` function against the package -imperatively, using `kpt fn eval`: +The package is now in the `regional` directory. So you can run `set-labels` function against the package imperatively, +using `kpt fn eval`: ```bash kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site-type=regional" "nephio.org/region=us-west1" @@ -142,7 +142,7 @@ kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site The output is similar to: -```console +```bash [RUNNING] "gcr.io/kpt-fn/set-labels:v0.2.0" [PASS] "gcr.io/kpt-fn/set-labels:v0.2.0" in 2.6s Results: @@ -164,7 +164,7 @@ porchctl rpkg push -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regi The output is similar to: -```console +```bash [RUNNING] "gcr.io/kpt-fn/apply-replacements:v0.1.1" [PASS] "gcr.io/kpt-fn/apply-replacements:v0.1.1" ``` @@ -179,7 +179,7 @@ porchctl rpkg propose -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 The output is similar to: -```console +```bash mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 proposed ``` @@ -191,7 +191,7 @@ porchctl rpkg approve -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 The output is similar to: -```console +```bash mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 approved ``` @@ -213,7 +213,7 @@ kubectl get clusters.cluster.x-k8s.io The output is similar to: -```console +```bash NAME PHASE AGE VERSION regional Provisioned 52m v1.26.3 ``` @@ -236,7 +236,7 @@ kubectl get ns --context regional-admin@regional The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 142m config-management-system Active 142m @@ -260,7 +260,7 @@ kubectl get machinesets The output is similar to: -```console +```bash NAME CLUSTER REPLICAS READY AVAILABLE AGE VERSION regional-md-0-m6cr5-wtzlx regional 1 1 1 5m36s v1.26.3 ``` @@ -277,7 +277,7 @@ kubectl apply -f test-infra/e2e/tests/free5gc/002-edge-clusters.yaml The output is similar to: -```console +```bash packagevariantset.config.porch.kpt.dev/edge-clusters created ``` @@ -292,7 +292,7 @@ kubectl get machinesets The output is similar to: -```console +```bash NAME CLUSTER REPLICAS READY AVAILABLE AGE VERSION edge01-md-0-rts82-q2vkr edge01 1 1 1 104m v1.26.3 edge02-md-0-kwn67-74tpw edge02 1 1 1 104m v1.26.3 @@ -322,7 +322,7 @@ source ~/.bash_profile ``` Once the Edge clusters are ready, it is necessary to connect them. For now you are using the -[containerlab tool](https://containerlab.dev/). Eventually, the inter-cluster networking will be automated as well. +[Containerlab tool](https://containerlab.dev/). Eventually, the inter-cluster networking will be automated as well. ```bash export E2EDIR=${E2EDIR:-$HOME/test-infra/e2e} @@ -334,7 +334,7 @@ export TESTDIR=${TESTDIR:-$HOME/test-infra/e2e/tests/free5gc} The output is similar to: -```console +```bash {"workers":["edge01-md-0-rts82-q2vkr-7cw86","edge02-md-0-kwn67-74tpw-v6x96","regional-md-0-lvmvm-8msw6-r67f6"]} INFO[0000] Containerlab v0.42.0 started INFO[0000] Parsing & checking topology file: clab-topo.gotmpl @@ -384,7 +384,7 @@ kubectl apply -f test-infra/e2e/tests/free5gc/002-network.yaml The output is similar to: -```console +```bash packagevariant.config.porch.kpt.dev/network created ``` @@ -398,7 +398,7 @@ kubectl apply -f test-infra/e2e/tests/free5gc/002-secret.yaml The output is similar to: -```console +```bash secret/srl.nokia.com created ``` @@ -415,7 +415,7 @@ also the credentials and information is provided to configure the network device The output is similar to: -```console +```bash rawtopology.topo.nephio.org/nephio created ``` @@ -451,7 +451,7 @@ kubectl get ns --context regional-admin@regional The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 28m config-management-system Active 28m @@ -474,7 +474,7 @@ kubectl -n free5gc-cp get all --context regional-admin@regional
The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE pod/free5gc-ausf-7d494d668d-k55kb 1/1 Running 0 3m31s pod/free5gc-nrf-66cc98cfc5-9mxqm 1/1 Running 0 3m31s @@ -532,7 +532,7 @@ kubectl apply -f test-infra/e2e/tests/free5gc/004-free5gc-operator.yaml The output is similar to: -```console +```bash packagevariantset.config.porch.kpt.dev/free5gc-operator created ``` @@ -549,7 +549,7 @@ kubectl get ns --context edge01-admin@edge01 The output is similar to: -```console +```bash NAME STATUS AGE config-management-monitoring Active 3h46m config-management-system Active 3h46m @@ -569,7 +569,7 @@ kubectl -n free5gc get all --context edge01-admin@edge01 The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE pod/free5gc-operator-controller-controller-58df9975f4-sglj6 2/2 Running 0 164m @@ -610,7 +610,7 @@ kubectl -n free5gc-upf logs $UPF1_POD --context edge01-admin@edge01
The output is similar to: -```console +```bash 2023-07-15T09:05:51Z [INFO][UPF][Main] UPF version: free5GC version: v3.2.1 build time: 2023-06-09T16:41:08Z @@ -677,7 +677,7 @@ kubectl -n free5gc-cp logs $AMF_POD --context regional-admin@regional The output is similar to: -```console +```bash 2023-07-15T09:08:55Z [INFO][AMF][CFG] config version [1.0.3] 2023-07-15T09:08:55Z [INFO][AMF][Init] AMF Log level is set to [info] level 2023-07-15T09:08:55Z [INFO][LIB][NAS] set log level : info @@ -713,7 +713,7 @@ kubectl -n free5gc-cp logs $SMF_POD --context regional-admin@regional The output is similar to: -```console +```bash 2023-07-15T09:10:45Z [INFO][SMF][CFG] SMF config version [1.0.2] 2023-07-15T09:10:45Z [INFO][SMF][CFG] UE-Routing config version [1.0.1] 2023-07-15T09:10:45Z [INFO][SMF][Init] SMF Log level is set to [debug] level @@ -797,7 +797,7 @@ kubectl --kubeconfig edge01-kubeconfig -n ueransim get pod The output is similar to: -```console +```bash NAME READY STATUS RESTARTS AGE ueransimgnb-edge01-748b45f684-sbs8h 1/1 Running 0 81m ueransimue-edge01-56fccbc4b6-h42k7 1/1 Running 0 81m @@ -815,7 +815,7 @@ kubectl --kubeconfig edge01-kubeconfig -n ueransim exec -it $UE_POD -- /bin/bash The output is similar to: -```console +```bash PING 172.0.0.1 (172.0.0.1) from 10.1.0.2 uesimtun0: 56(84) bytes of data. 64 bytes from 172.0.0.1: icmp_seq=1 ttl=63 time=7.01 ms 64 bytes from 172.0.0.1: icmp_seq=2 ttl=63 time=6.28 ms @@ -852,7 +852,7 @@ kubectl get packagevariant edge-free5gc-upf-edge01-free5gc-upf -o jsonpath='{.st The output is similar to: -```console +```bash edge01-6b26ca0f4fdf83212a73faff159bd013b41207ee ``` @@ -868,12 +868,12 @@ porchctl rpkg copy -n default edge01-6b26ca0f4fdf83212a73faff159bd013b41207ee -- The output is similar to: -```console +```bash edge01-40c616e5d87053350473d3ffa1387a9a534f8f42 created ``` -The output contains the package revision of our newly cloned upf package. Pull the package to a local directory of your +The output contains the package revision of our newly cloned UPF package. Pull the package to a local directory of your choice (in the example you can use /tmp/upf-scale-package). ```bash @@ -888,7 +888,7 @@ cat /tmp/upf-scale-package/capacity.yaml The output is similar to: -```console +```bash apiVersion: req.nephio.org/v1alpha1 kind: Capacity metadata: # kpt-merge: /dataplane @@ -905,8 +905,8 @@ spec: The contents of the package will be mutated using kpt functions to adjust the UPF configuration, however you can also -manually edit the file. Apply the kpt functions to the contents of the kpt package with a new value for the throughputs -of your choice. +manually edit the file. Apply the kpt functions to the contents of the kpt package with a new value for the throughput +values of your choice. ```bash kpt fn eval --image gcr.io/kpt-fn/search-replace:v0.2.0 /tmp/upf-scale-package -- by-path='spec.maxUplinkThroughput' by-file-path='**/capacity.yaml' put-value=10 @@ -915,7 +915,7 @@ kpt fn eval --image gcr.io/kpt-fn/search-replace:v0.2.0 /tmp/upf-scale-package - The output is similar to: -```console +```bash [RUNNING] "gcr.io/kpt-fn/search-replace:v0.2.0" [PASS] "gcr.io/kpt-fn/search-replace:v0.2.0" in 6.3s Results: @@ -936,7 +936,7 @@ kpt pkg diff /tmp/upf-scale-package | grep linkThroughput The output is similar to: -```console +```bash From https://github.com/nephio-project/catalog * tag workloads/free5gc/pkg-example-upf-bp/v2.0.0 -> FETCH_HEAD Adding package "workloads/free5gc/pkg-example-upf-bp". @@ -960,7 +960,7 @@ porchctl rpkg approve -n default edge01-40c616e5d87053350473d3ffa1387a9a534f8f42 The output is similar to: -```console +```bash [RUNNING] "gcr.io/kpt-fn/apply-replacements:v0.1.1" [PASS] "gcr.io/kpt-fn/apply-replacements:v0.1.1" [RUNNING] "gcr.io/kpt-fn/apply-replacements:v0.1.1" @@ -996,7 +996,7 @@ porchctl rpkg get | grep free5gc-upf The output is similar to: -```console +```bash NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY edge01-5e5621cee05df46c3e9ad6dd50ab485f4ebeeffd free5gc-upf upf-scale-package main false Published edge01 edge01-6b26ca0f4fdf83212a73faff159bd013b41207ee free5gc-upf packagevariant-1 v1 false Published edge01 @@ -1050,4 +1050,11 @@ After saving the changes to the file, propose the draft package and approve it. After a few minutes, the revision for the UPF deployment will change, and the changes will be reflected in the `edge-02` cluster. -**NOTE**: You will observe that the UPF NFDeployment on the workload clusters is updated and synced with Gitea. The UPF pod will not reflect the new information. This is because the Nephio free5gc operator is not updating the pod with new configuration. +{{% alert title="Note" color="primary" %}} + +You will observe that the UPF NFDeployment on the workload clusters is updated and synced with Gitea. The UPF pod will +not reflect the new information. This is because the Nephio free5gc operator is not updating the pod with new +configuration. + +{{% /alert %}} + diff --git a/content/en/docs/porch/_index.md b/content/en/docs/porch/_index.md index a85ad913..80f3790b 100644 --- a/content/en/docs/porch/_index.md +++ b/content/en/docs/porch/_index.md @@ -18,7 +18,7 @@ Porch is a key component of the Nephio architecture and was originally developed [kpt](https://github.com/kptdev/kpt) project. When kpt was donated to the [CNCF](https://www.cncf.io/projects/kpt/) it was decided that Porch would not be part of the kpt project and the code was donated to Nephio. -Porch is now mainteined by the Nephio community and it is a stable part of the Nephio R3 architecture. However there is -an active disucssion about the future of the project. It is possible that the current Porch component will be replaced in the Nephio -architecture with a different codebase implementing the same concepts but not in a backward compatible way. Potential -candidates such as [pkgserver](https://docs.pkgserver.dev/) are being discussed in the Nephio community. \ No newline at end of file +Porch is now maintained by the Nephio community and it is a stable part of the Nephio R3 architecture. However there is +an active discucssion about the future of the project. It is possible that the current Porch component will be replaced +in the Nephio architecture with a different codebase implementing the same concepts but not in a backward compatible +way. Potential candidates such as [pkgserver](https://docs.pkgserver.dev/) are being discussed in the Nephio community. \ No newline at end of file diff --git a/content/en/docs/porch/contributors-guide/_index.md b/content/en/docs/porch/contributors-guide/_index.md index 349a0af9..ac36d9d3 100644 --- a/content/en/docs/porch/contributors-guide/_index.md +++ b/content/en/docs/porch/contributors-guide/_index.md @@ -17,7 +17,7 @@ make generate Porch comprises of several software components: -* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch +* [API](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch extension apiserver * [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of Porch `Repository` and `PackageRevision` custom resources. @@ -69,7 +69,7 @@ Follow the [Running Porch Locally](../running-porch/running-locally.md) guide to ## Debugging To debug Porch, run Porch locally [running-locally.md](../running-porch/running-locally.md), exit porch server running -in the shell, and launch Porch under the debugger. VSCode debug session is pre-configured in +in the shell, and launch Porch under the debugger. VS Code debug session is pre-configured in [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json). Update the launch arguments to your needs. @@ -91,7 +91,7 @@ Some useful code pointers: All tests can be run using `make test`. Individual tests can be run using `go test`. End-to-End tests assume that Porch instance is running and `KUBECONFIG` is configured with the instance. The tests will automatically detect whether they are running against -Porch running on local machien or k8s cluster and will start Git server appropriately, +Porch running on local machine or k8s cluster and will start Git server appropriately, then run test suite against the Porch instance. ## Makefile Targets @@ -109,8 +109,8 @@ then run test suite against the Porch instance. * `make` or `make all`: builds and runs Porch [locally](../running-porch/running-locally.md) * `make test`: runs tests -## VSCode +## VS Code -[VSCode](https://code.visualstudio.com/) works really well for editing and debugging. -Just open VSCode from the root folder of the Porch repository and it will work fine. The folder contains the needed -configuration to Launch different functions of Proch. \ No newline at end of file +[VS Code](https://code.visualstudio.com/) works really well for editing and debugging. +Just open VS Code from the root folder of the Porch repository and it will work fine. The folder contains the needed +configuration to Launch different functions of Porch. \ No newline at end of file diff --git a/content/en/docs/porch/contributors-guide/dev-process.md b/content/en/docs/porch/contributors-guide/dev-process.md index ec84f685..c20acc82 100644 --- a/content/en/docs/porch/contributors-guide/dev-process.md +++ b/content/en/docs/porch/contributors-guide/dev-process.md @@ -27,11 +27,11 @@ make run-in-kind-no-server After issuing this command you are expected to start the porch API server locally on your machine (outside of the kind cluster); probably in your IDE, potentially in a debugger. -### Configure VSCode to run the Porch (api)server +### Configure VS Code to run the Porch (API)server -The simplest way to run the porch API server is to launch it in a VSCode IDE, as described by the following process: +The simplest way to run the porch API server is to launch it in a VS Code IDE, as described by the following process: -1. Open the `porch.code-workspace` file in the root of the porch git repo. +1. Open the `porch.code-workspace` file in the root of the porch git repository. 1. Edit your local `.vscode/launch.json` file as follows: Change the `--kubeconfig` argument of the `Launch Server` configuration to point to a KUBECONFIG file that is set to the kind cluster as the current context. @@ -41,7 +41,7 @@ The simplest way to run the porch API server is to launch it in a VSCode IDE, as {{% /alert %}} -1. Launch the Porch server locally in VSCode by selecting the "Launch Server" configuration on the VSCode "Run and Debug" window. For more information please refer to the [VSCode debugging documentation](https://code.visualstudio.com/docs/editor/debugging). +1. Launch the Porch server locally in VS Code by selecting the "Launch Server" configuration on the VS Code "Run and Debug" window. For more information please refer to the [VS Code debugging documentation](https://code.visualstudio.com/docs/editor/debugging). ### Check to ensure that the API server is serving requests: @@ -137,7 +137,10 @@ The following command will rebuild and deploy porch, except the porch-controller make run-in-kind-no-controllers ``` -After issuing this command you are expected to start the porch controllers process locally on your machine (outside of the kind cluster); probably in your IDE, potentially in a debugger. If you are using VS Code you can use the "Launch Controllers" configuration that is defined in the [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json) file of the porch git repo. +After issuing this command you are expected to start the porch controllers process locally on your machine (outside of +the kind cluster); probably in your IDE, potentially in a debugger. If you are using VS Code you can use the +"Launch Controllers" configuration that is defined in the +[launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json) file of the porch git repository. ## Run the unit tests @@ -147,13 +150,13 @@ make test ## Run the end-to-end tests -To run the end-to-end tests against the Kubernetes API server where KUBECONFIG points to, simply issue: +To run the end-to-end tests against the Kubernetes API server where KUBECONFIG points to, issue: ```bash make test-e2e ``` -To run the end-to-end tests against a clean deployment, simply issue: +To run the end-to-end tests against a clean deployment, issue: ```bash make test-e2e-clean diff --git a/content/en/docs/porch/contributors-guide/environment-setup-vm.md b/content/en/docs/porch/contributors-guide/environment-setup-vm.md index 4b4945dc..450e95ba 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup-vm.md +++ b/content/en/docs/porch/contributors-guide/environment-setup-vm.md @@ -98,14 +98,14 @@ cd porch sed -i "s/^KIND_CONTEXT_NAME ?= porch-test$/KIND_CONTEXT_NAME ?= "$(kind get clusters)"/" Makefile ``` -9. Expose the Porch function runner so that the Nephio server running in VSCode can access it +9. Expose the Porch function runner so that the Nephio server running in VS Code can access it ```bash kubectl expose svc -n porch-system function-runner --name=xfunction-runner --type=LoadBalancer --load-balancer-ip='172.18.0.202' ``` 10. Set the `KUBECONFIG` and `FUNCTION_RUNNER_IP` environment variables in the `.profile` file -You **must** do this step before connecting with VSCode because VSCode caches the environment on the server. If you want to change the values of these variables subsequently, you must restart the VM server. +You **must** do this step before connecting with VS Code because VS Code caches the environment on the server. If you want to change the values of these variables subsequently, you must restart the VM server. ```bash echo '' >> ~/.profile @@ -115,44 +115,44 @@ echo 'export FUNCTION_RUNNER_IP="172.18.0.202"' >> ~/.profile You have now set up the VM so that it can be used for remove debugging of Porch. -## Setting up VSCode +## Setting up VS Code -Use the [VSCode Remote SSH] +Use the [VS Code Remote SSH] (https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) -plugin to To debug from VSCode running on your local machine towards a VM. Detailed documentation +plugin to To debug from VS Code running on your local machine towards a VM. Detailed documentation on the plugin and its use is available on the -[Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh) in the VSCode +[Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh) in the VS Code documentation. 1. Use the **Connect to a remote host** instructions on the [Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh) page to connect to your VM. -2. Click **Open Folder** and browse to the Porch code on the vm, `/home/ubuntu/git/github/nephio-project/porch` in this case: +2. Click **Open Folder** and browse to the Porch code on the VM, `/home/ubuntu/git/github/nephio-project/porch` in this case: ![Browse to Porch code](/static/images/porch/contributor/01_VSCodeOpenPorchFolder.png) -3. VSCode now opens the Porch project on the VM. +3. VS Code now opens the Porch project on the VM. ![Porch code is open](/static/images/porch/contributor/02_VSCodeConnectedPorch.png) -4. We now need to install support for `go` debugging in VSCode. Trigger this by launching a debug configuration in VSCode. +4. We now need to install support for `go` debugging in VS Code. Trigger this by launching a debug configuration in VS Code. Here we use the **Launch Override Server** configuration. -![Launch the Override Server VSCode debug configuration](/static/images/porch/contributor/03_LaunchOverrideServer.png) +![Launch the Override Server VS Code debug configuration](/static/images/porch/contributor/03_LaunchOverrideServer.png) -5. VSCode complains that `go` debugging is not supported, click the **Install go Extension** button. +5. VS Code complains that `go` debugging is not supported, click the **Install go Extension** button. -![VSCode go debugging not supported message](/static/images/porch/contributor/04_GoDebugNotSupportedPopup.png) +![VS Code go debugging not supported message](/static/images/porch/contributor/04_GoDebugNotSupportedPopup.png) 6. Go automatically presents the Go debug plugin for installation. Click the **Install** button. -![VSCode Go debugging plugin selected](/static/images/porch/contributor/05_GoExtensionAutoSelected.png) +![VS Code Go debugging plugin selected](/static/images/porch/contributor/05_GoExtensionAutoSelected.png) -7. VSCode installs the plugin. +7. VS Code installs the plugin. -![VSCode Go debugging plugin installed](/static/images/porch/contributor/06_GoExtensionInstalled.png) +![VS Code Go debugging plugin installed](/static/images/porch/contributor/06_GoExtensionInstalled.png) -You have now set up VSCode so that it can be used for remove debugging of Porch. +You have now set up VS Code so that it can be used for remove debugging of Porch. ## Getting started with actual development diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 3e86ea77..6f0039e4 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -12,8 +12,8 @@ through the [Starting with Porch tutorial](../using-porch/install-and-using-porc {{% alert title="Note" color="primary" %}} -As your Dev environment, you can run the code on a remote VM and use the -[VSCode Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) +As your development environment, you can run the code on a remote VM and use the +[VS Code Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) plugin to connect to it. {{% /alert %}} @@ -24,7 +24,7 @@ The script the `make deployment-config` target to generate the deployment files make target use recent `bash` additions. MacOS comes with `bash` 3.x.x 1. Install `bash` 4.x.x or better of `bash` using homebrew, see - [this this post for details](https://apple.stackexchange.com/questions/193411/update-bash-to-version-4-0-on-osx) + [this post for details](https://apple.stackexchange.com/questions/193411/update-bash-to-version-4-0-on-osx) 2. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin` {{% alert title="Note" color="primary" %}} @@ -127,7 +127,7 @@ packages porch.kpt.dev/v1alpha1 To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../using-porch/install-and-using-porch.md) tutorial to create the repositories in Porch. -You will notice logging messages in VSCode when you run the `kubectl apply -f porch-repositories.yaml` command. +You will notice logging messages in VS Code when you run the `kubectl apply -f porch-repositories.yaml` command. You can check that your locally running Porch server has created the repositories by running the `porchctl` command: @@ -157,12 +157,12 @@ external-blueprints git Package false True https://github.com/n management git Package false True http://172.18.255.200:3000/nephio/management.git ``` -You now have a locally running Porch (api)server. Happy developing! +You now have a locally running Porch (API)server. Happy developing! ## Restart from scratch Sometimes the development cluster gets cluttered and you may experience weird behavior from porch. -In this case you might want to restart with a clean slate, by deleting the development cluster with the following +In this case you might want to restart from scratch, by deleting the development cluster with the following command: ```bash diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index a687b658..f1b6d512 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -73,7 +73,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [kpt][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [kpt][] - a Git-native, schema-aware, extendable client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle @@ -401,8 +401,7 @@ Orchestration service. ## User Guide -Find the Porch User Guide in a dedicated -[document](https://github.com/kptdev/kpt/blob/main/site/guides/porch-user-guide.md). +Find the Porch User Guide in a dedicated [document](using-porch/usage-porch-kpt-cli). ## Open Issues/Questions diff --git a/content/en/docs/porch/package-variant.md b/content/en/docs/porch/package-variant.md index 7ef66109..3209241a 100644 --- a/content/en/docs/porch/package-variant.md +++ b/content/en/docs/porch/package-variant.md @@ -1017,7 +1017,7 @@ spec: org: hr ``` -When using other targeting means, the use of the `Expr` fields becomes more likely, because we have more possible +When using other targeting means, the use of the `Expr` fields becomes more likely, because we have more probable sources for different field values. The `Expr` values are all [Common Expression Language (CEL)](https://github.com/google/cel-go) expressions, rather than static values. This allows the user to construct values based upon various fields of the targets. Consider again the `repositorySelector` example, @@ -1206,7 +1206,7 @@ The PackageVariantSet status uses these conditions: [^porch18]: Coming in Porch v0.0.18. [^notimplemented]: Proposed here but not yet implemented as of Porch v0.0.18. [^setns]: As of this writing, the `set-namespace` function does not have a `create` option. This should be added to - avoid the user needing to also usethe `upsert-resource` function. Such common operation should be simple forusers. + avoid the user needing to also use the `upsert-resource` function. Such common operation should be simple for users. [^pvsimpl]: This document describes PackageVariantSet `v1alpha2`, which will be available starting with Porch v0.0.18. In Porch v0.0.16 and 17, the `v1alpha1` implementation is available, but it is a somewhat different API, without support for CEL or any injection. It is focused only on fan out targeting, and uses a [slightly different targeting API](https://github.com/nephio-project/porch/blob/main/controllers/packagevariants/api/v1alpha1/packagevariant_types.go). diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index 0c19468b..5893cff2 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -12,7 +12,7 @@ You can install Porch by either using one of the {{% alert title="Note" color="primary" %}} -Porch should run on any kubernetes cluster and should work on any cloud. We have just started by documenting one +Porch should run on any Kubernetes cluster and should work on any cloud. We have just started by documenting one known-good configuration: GCP and GKE. We would welcome comparable installation instructions or feedback from people that try it out on other clouds / configurations. @@ -147,7 +147,7 @@ cluster manually following the The `-no-sa` (no service account) targets create Porch deployment configuration which does not associate Kubernetes service accounts with GCP -service accounts. This is sufficient for Porch to integate with Git repositories +service accounts. This is sufficient for Porch to integrate with Git repositories using Basic Auth, for example GitHub. As above, you can verify that Porch is running by querying the `api-resources`: @@ -160,7 +160,7 @@ kubectl api-resources | grep porch ### Workload Identity [Workload Identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity) is a simple way to -access Google Cloud services from porch. +access Google Cloud services from Porch. #### Google Cloud Source Repositories @@ -191,7 +191,7 @@ kubectl annotate serviceaccount porch-server -n porch-system \ iam.gke.io/gcp-service-account=porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com ``` -Build Porch, push images, and deploy porch server and controllers using the `make` target that adds workload identity +Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity service account annotations: ```bash @@ -246,7 +246,7 @@ gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}. --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]" ``` -Build Porch, push images, and deploy porch server and controllers using the `make` target that adds workload identity +Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity service account annotations: ```bash diff --git a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md b/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md index 8b20a5f4..033ff4f1 100644 --- a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md +++ b/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md @@ -6,8 +6,8 @@ description: "" --- To enable the porch server to communicate with a custom git deployment over HTTPS, we must: -1. Provide a additional args flag `use-git-cabundle=true` to the porch-server deployment. -2. Provide an additional kubernetes secret containing the relevant certificate chain in the form of a cabundle. +1. Provide an additional arguments flag `use-git-cabundle=true` to the porch-server deployment. +2. Provide an additional Kubernetes secret containing the relevant certificate chain in the form of a cabundle. The secret itself must meet the following criteria: @@ -19,13 +19,13 @@ For example, a Git Repository is hosted over HTTPS at the following URL: `https://my-gitlab.com/joe.bloggs/blueprints.git` -Before creating the new Repository in the **gitlab** namespace, we must create a secret that fulfils the criteria above. +Before creating the new Repository in the **GitLab** namespace, we must create a secret that fulfils the criteria above. `kubectl create secret generic gitlab-ca-bundle --namespace=gitlab --from-file=ca.crt` Which would produce the following: -``` +```yaml apiVersion: v1 kind: Secret metadata: diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index ca23fd1b..4693614b 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -7,14 +7,14 @@ description: "A tutorial to install and use Porch" This tutorial is a guide to installing and using Porch. It is based on the [Porch demo produced by Tal Liron of Google](https://github.com/tliron/klab/tree/main/environments/porch-demo). Users -should be very comfortable with using `git`, `docker`, and `kubernetes`. +should be comfortable with using `git`, `docker`, and `kubernetes`. See also [the Nephio Learning Resource](https://github.com/nephio-project/docs/blob/main/learning.md) page for background help and information. ## Prerequisites -The tutorial can be executed on a Linux VM or directly on a laptop. It has been verified to execute on a Macbook Pro M1 +The tutorial can be executed on a Linux VM or directly on a laptop. It has been verified to execute on a MacBook Pro M1 machine and an Ubuntu 20.04 VM. The following software should be installed prior to running through the tutorial: @@ -28,7 +28,7 @@ The following software should be installed prior to running through the tutorial 7. [Visual Studio Code](https://code.visualstudio.com/download) 8. [VS Code extensions for go](https://code.visualstudio.com/docs/languages/go) -## Clone the repo and cd into the tutorial +## Clone the repository and cd into the tutorial ```bash git clone https://github.com/nephio-project/porch.git @@ -102,9 +102,9 @@ Apply the MetalLB configuration: kubectl apply -f metallb-conf.yaml ``` -## Deploy and set up gitea on the management cluster using kpt +## Deploy and set up Gitea on the management cluster using kpt -Get the gitea kpt package: +Get the Gitea kpt package: ```bash export KUBECONFIG=~/.kube/kind-management-config @@ -114,7 +114,7 @@ cd kpt_packages kpt pkg get https://github.com/nephio-project/catalog/tree/main/distros/sandbox/gitea ``` -Comment out the preconfigured IP address from the `gitea/service-gitea.yaml` file in the gitea Kpt package: +Comment out the preconfigured IP address from the `gitea/service-gitea.yaml` file in the Gitea Kpt package: ```bash 11c11 @@ -131,7 +131,7 @@ kpt live init gitea # You only need to do this command once kpt live apply gitea ``` -Once the package is applied, all the gitea pods should come up and you should be able to reach the Gitea UI on the exposed IP Address/port of the gitea service. +Once the package is applied, all the Gitea pods should come up and you should be able to reach the Gitea UI on the exposed IP Address/port of the Gitea service. ```bash kubectl get svc -n gitea gitea @@ -146,12 +146,12 @@ To login to Gitea, use the credentials `nephio:secret`. ## Create repositories on Gitea for management and edge1 -On the gitea UI, click the '+' opposite "Repositories" and fill in the form for both the `management` and `edge1` repositories. Use default values except for the following fields: +On the Gitea UI, click the '+' opposite "Repositories" and fill in the form for both the `management` and `edge1` repositories. Use default values except for the following fields: - Repository Name: "Management" or "edge1" - Description: Something appropriate -Alternatively, we can create the repos via curl: +Alternatively, we can create the repositories via curl: ```bash curl -k -H "content-type: application/json" "http://nephio:secret@172.18.255.200:3000/api/v1/user/repos" --data '{"name":"management"}' @@ -165,7 +165,7 @@ Check the repos: curl -k -H "content-type: application/json" "http://nephio:secret@172.18.255.200:3000/api/v1/user/repos" | grep -Po '"name": *\K"[^"]*"' ``` -Now initialize both repos with an initial commit. +Now initialize both repositories with an initial commit. Initialize the `management` repo @@ -310,13 +310,13 @@ config-management-operator-6946b77565-f45pc 1/1 Running 0 118m reconciler-manager-5b5d8557-gnhb2 2/2 Running 0 118m ``` -Now, we need to set up a Rootsync CR to synchronize the `edge1` repo: +Now, we need to set up a rootsync CR to synchronize the `edge1` repo: ```bash kpt pkg get https://github.com/nephio-project/catalog/tree/main/nephio/optional/rootsync ``` -Edit the `rootsync/package-context.yaml` file to set the name of the cluster/repo we are syncing from/to: +Edit the `rootsync/package-context.yaml` file to set the name of the cluster/repository we are syncing from/to: ```bash 9c9 @@ -332,7 +332,7 @@ kpt fn render rootsync ``` Edit the `rootsync/rootsync.yaml` file to set the IP address of Gitea and to turn off authentication for accessing -gitea: +Gitea: ```bash 11c11 @@ -359,7 +359,7 @@ kpt live init rootsync # This command is only needed once kpt live apply rootsync ``` -Check that the RootSync CR is created: +Check that the rootsync CR is created: ```bash kubectl get rootsync -n config-management-system @@ -367,7 +367,7 @@ NAME RENDERINGCOMMIT RENDERINGERRORCOUNT SOURCEC edge1 613eb1ad5632d95c4336894f8a128cc871fb3266 613eb1ad5632d95c4336894f8a128cc871fb3266 613eb1ad5632d95c4336894f8a128cc871fb3266 ``` -Check that Configsync is synchronized with the repo on the management cluster: +Check that Configsync is synchronized with the repository on the management cluster: ```bash kubectl get pod -n config-management-system -l app=reconciler @@ -445,7 +445,7 @@ kubectl get crd -n porch-system repositories.config.porch.kpt.dev -o yaml kubectl describe crd -n porch-system repositories.config.porch.kpt.dev ``` -You can of course examine any other CRD using the commands above and changing the CRD name/namespace. +You can examine any other CRD using the commands above and changing the CRD name/namespace. The full list of Nephio CRDs is as below: @@ -1352,7 +1352,7 @@ The output above is similar to the output of `kubectl get packagerevision -n por ### Blueprint with no Kpt pipelines -Create a new package in our `management` repo using the sample `network-function` package provided. This network function kpt package is a demo Kpt package that installs [nginx](https://github.com/nginx). +Create a new package in our `management` repository using the sample `network-function` package provided. This network function kpt package is a demo Kpt package that installs [Nginx](https://github.com/nginx). ``` porchctl -n porch-demo rpkg init network-function --repository=management --workspace=v1 @@ -1362,7 +1362,7 @@ NAME PACKAGE WORKSPA management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Draft management ``` -This command creates a new PackageRevision CR in porch and also creates a branch called `network-function/v1` in our gitea `management` repo. Use the Gitea web UI to confirm that the branch has been created and note that it only has default content as yet. +This command creates a new PackageRevision CR in porch and also creates a branch called `network-function/v1` in our Gitea `management` repo. Use the Gitea web UI to confirm that the branch has been created and note that it only has default content as yet. We now pull the package we have initialized from Porch. @@ -1401,11 +1401,11 @@ management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 ``` -Once we approve the package, the package is merged into the main branch in the `management` repo and the branch called `network-function/v1` in that repo is removed. Use the Gitea UI to verify this. We now have our blueprint package in our `management` repo and we can deploy this package into workload clusters. +Once we approve the package, the package is merged into the main branch in the `management` repository and the branch called `network-function/v1` in that repository is removed. Use the Gitea UI to verify this. We now have our blueprint package in our `management` repository and we can deploy this package into workload clusters. ### Blueprint with a Kpt pipeline -The second blueprint blueprint in the `blueprint` directory is called `network-function-auto-namespace`. This network function is exactly the same as the `network-function` package except that it has a Kpt function that automatically creates a namespace with the namespace configured in the `name` field in the `package-context.yaml` file. Note that no namespace is defined in the metadata of the `deployment.yaml` file of this Kpt package. +The second blueprint in the `blueprint` directory is called `network-function-auto-namespace`. This network function is exactly the same as the `network-function` package except that it has a Kpt function that automatically creates a namespace with the namespace configured in the `name` field in the `package-context.yaml` file. Note that no namespace is defined in the metadata of the `deployment.yaml` file of this Kpt package. We use the same sequence of commands again to publish our blueprint package for `network-function-auto-namespace`. @@ -1420,7 +1420,7 @@ cp blueprints/local-changes/network-function-auto-namespace/* blueprints/initial porchctl -n porch-demo rpkg push management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace ``` -Examine the `drafts/network-function-auto-namespace/v1` branch in Gitea. Notice that the `set-namespace` Kpt finction in the pipeline in the `Kptfile` has set the namespace in the `deployment.yaml` file to the value `default-namespace-name`, which it read from the `package-context.yaml` file. +Examine the `drafts/network-function-auto-namespace/v1` branch in Gitea. Notice that the `set-namespace` Kpt function in the pipeline in the `Kptfile` has set the namespace in the `deployment.yaml` file to the value `default-namespace-name`, which it read from the `package-context.yaml` file. Now we propose and approve the package. @@ -1442,7 +1442,7 @@ management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-name ### Blueprint with no Kpt pipelines -The process of deploying a blueprint package from our `management` repo clones the package, then modifies it for use on the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the `edge1` repo. Remember that the `edge1` repo is being monitored by Configsync from the `edge1` cluster, so once the package appears in the `edge1` repo on the management cluster, it will be pulled by Configsync and applied to the `edge1` cluster. +The process of deploying a blueprint package from our `management` repository clones the package, then modifies it for use on the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the `edge1` repo. Remember that the `edge1` repository is being monitored by Configsync from the `edge1` cluster, so once the package appears in the `edge1` repository on the management cluster, it will be pulled by Configsync and applied to the `edge1` cluster. ``` porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp @@ -1490,7 +1490,7 @@ NAME PACKAGE WORKSPACEN edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 false Draft edge1 ``` -You can verify that the package is in the `network-function-a/v1` branch of the deployment repo using the Gitea web UI. +You can verify that the package is in the `network-function-a/v1` branch of the deployment repository using the Gitea web UI. Check that the `edge1-network-function-a` package is not deployed on the edge1 cluster yet: @@ -1502,7 +1502,7 @@ No resources found in network-function-a namespace. ``` -We now propose and approve the deployment package, which merges the package to the `edge1` repo and further triggers Configsync to apply the package to the `edge1` cluster. +We now propose and approve the deployment package, which merges the package to the `edge1` repository and further triggers Configsync to apply the package to the `edge1` cluster. ``` export KUBECONFIG=~/.kube/kind-management-config @@ -1569,7 +1569,7 @@ rm -fr tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone ``` -We now simply configure the namespace we want to apply. edit the `tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml` file and set the namespace to use: +We now configure the namespace we want to apply. edit the `tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml` file and set the namespace to use: ``` 8c8 @@ -1590,7 +1590,7 @@ porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a ``` -You can verify that the package is in the `network-function-auto-namespace-a/v1` branch of the deployment repo using the Gitea web UI. You can see that the kpt pipeline fired and set the `edge1-network-function-auto-namespace-a` namespace in the `deployment.yaml` file on the `drafts/edge1-network-function-auto-namespace-a/v1` branch on the `edge1` repo in gitea. +You can verify that the package is in the `network-function-auto-namespace-a/v1` branch of the deployment repository using the Gitea web UI. You can see that the kpt pipeline fired and set the `edge1-network-function-auto-namespace-a` namespace in the `deployment.yaml` file on the `drafts/edge1-network-function-auto-namespace-a/v1` branch on the `edge1` repository in Gitea. Check that the `edge1-network-function-auto-namespace-a` package is not deployed on the edge1 cluster yet: ``` @@ -1601,7 +1601,7 @@ No resources found in network-function-auto-namespace-a namespace. ``` -We now propose and approve the deployment package, which merges the package to the `edge1` repo and further triggers Configsync to apply the package to the `edge1` cluster. +We now propose and approve the deployment package, which merges the package to the `edge1` repository and further triggers Configsync to apply the package to the `edge1` cluster. ``` export KUBECONFIG=~/.kube/kind-management-config @@ -1660,7 +1660,7 @@ spec: - network-function-c ``` -In this very simple PackageVariant, the `network-function` package in the `management` repo is cloned into the `edge1` repo as the `network-function-b` and `network-function-c` package variants. +In this simple PackageVariant, the `network-function` package in the `management` repository is cloned into the `edge1` repository as the `network-function-b` and `network-function-c` package variants. {{% alert title="Note" color="primary" %}} @@ -1706,7 +1706,7 @@ network-function-c network-function-9779fc9f5-h7nsb ``` -It is also interesting to examine the yaml of the PackageVariant: +It is also interesting to examine the YAML of the PackageVariant: ```yaml kubectl get PackageVariant -n porch-demo -o yaml @@ -1799,7 +1799,7 @@ metadata: resourceVersion: "" ``` -We now want to customize and deploy our two packages. To do this we must pull the pacakges locally, render the kpt +We now want to customize and deploy our two packages. To do this we must pull the packages locally, render the kpt functions, and then push the rendered packages back up to the `edge1` repo. ```bash @@ -1812,7 +1812,7 @@ kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployme porchctl rpkg push edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo ``` -Check that the namespace has been updated on the two packages in the `edge1` repo using the Gitea web UI. +Check that the namespace has been updated on the two packages in the `edge1` repository using the Gitea web UI. Now our two packages are ready for deployment: @@ -1870,7 +1870,7 @@ spec: ``` -In this PackageVariant, the `network-function-auto-namespace` package in the `management` repo is cloned into the `edge1` repo as the `network-function-auto-namespace-x` and `network-function-auto-namespace-y` package variants, similar to the PackageVariant in `simple-variant.yaml`. +In this PackageVariant, the `network-function-auto-namespace` package in the `management` repository is cloned into the `edge1` repository as the `network-function-auto-namespace-x` and `network-function-auto-namespace-y` package variants, similar to the PackageVariant in `simple-variant.yaml`. An extra `template` section provided for the repositories in the PackageVariant: @@ -1884,11 +1884,11 @@ This template means that each package in the `spec.targets.repositories..package `-cumulus` added to its name. This allows us to automatically generate unique package names. Applying the PackageVariantSet also automatically sets a unique namespace for each network function because applying the PackageVariantSet automatically triggers the Kpt pipeline in the `network-function-auto-namespace` Kpt package to -gerenate unique namespaces for each deployed package. +generate unique namespaces for each deployed package. {{% alert title="Note" color="primary" %}} -Many other mutatinos can be performed using a PackageVariantSet. Use `kubectl explain PackageVariantSet` to get help on +Many other mutations can be performed using a PackageVariantSet. Use `kubectl explain PackageVariantSet` to get help on the structure of the PackageVariantSet CRD to see the various mutations that are possible. {{% /alert %}} @@ -1914,11 +1914,11 @@ management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function- {{% alert title="Note" color="primary" %}} -The suffix `x-cumulonimbus` and `y-cumulonimbus` has been palced on the package names. +The suffix `x-cumulonimbus` and `y-cumulonimbus` has been placed on the package names. {{% /alert %}} -Examine the `edge1` repo on Giea and you should see two new draft branches. +Examine the `edge1` repository on Gitea and you should see two new draft branches. - drafts/network-function-auto-namespace-x-cumulonimbus/packagevariant-1 - drafts/network-function-auto-namespace-y-cumulonimbus/packagevariant-1 @@ -1933,7 +1933,7 @@ In these packages, you will see that: `network-function-auto-namespace-y-cumulonimbus` respectively in the `pckage-context.yaml` files This has all been performed automatically; we have not had to perform the -`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these chages as we had to in the +`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these changes as we had to in the `simple-variant.yaml` case above. Now, let us explore the packages further: @@ -1960,7 +1960,7 @@ network-function-edge1-network-function-b 38m network-function-edge1-network-function-c 38m ``` -It is also interesting to examine the yaml of a PackageVariant: +It is also interesting to examine the YAML of a PackageVariant: ```yaml kubectl get PackageVariant -n porch-demo network-function-auto-namespace-edge1-network-function-35079f9f -o yaml diff --git a/content/en/docs/porch/using-porch/porchctl-cli-guide.md b/content/en/docs/porch/using-porch/porchctl-cli-guide.md index c630a688..78c40516 100644 --- a/content/en/docs/porch/using-porch/porchctl-cli-guide.md +++ b/content/en/docs/porch/using-porch/porchctl-cli-guide.md @@ -5,7 +5,7 @@ weight: 2 description: --- -## Using the porchctl cli +## Using the porchctl CLI When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved into a new command called `porchctl`. @@ -49,7 +49,8 @@ Use "porchctl [command] --help" for more information about a command. ``` -The `porchtcl` command is an administration command for acting on Porch `Repository` (repo) and `PackageRevision` (rpkg) CRs. +The `porchtcl` command is an administration command for acting on Porch `Repository` (repository) and `PackageRevision` +(rpkg) CRs. The commands for administering repositories are: diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md index 8b3b2d0a..6e99e1e5 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md @@ -28,7 +28,7 @@ To check whether `kubectl` is configured with your Porch cluster (or local insta kubectl api-resources | grep porch ``` -You should see the following four resourceds listed: +You should see the following four resources listed: ```bash repositories config.porch.kpt.dev/v1alpha1 true Repository @@ -168,7 +168,7 @@ Therefore, the names of the Kubernetes resources representing package revisions {{% /alert %}} -Simple filtering of package revisions by name (substring) and revision (exact match) is supported by the CLI using +Filtering of package revisions by name (substring) and revision (exact match) is supported by the CLI using `--name` and `--revision` flags: ```bash @@ -452,8 +452,8 @@ emphasize that Config Sync is the deploying mechanism and that configuration is target as a means of deployment) and include: * `create` - Creates a sync of a package in the deployment cluster. -* `del` - Deletes the package RootSync. -* `get` - Gets a RootSync resource with which package was deployed. +* `del` - Deletes the package rootsync. +* `get` - Gets a rootsync resource with which package was deployed. ```bash # Make sure Config Sync is configured to use multirepo mode @@ -472,7 +472,7 @@ $ kpt alpha sync create -ndefault \ --package=deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ sync-istions-clone -Created RootSync config-management-system/sync-istions-clone +Created rootsync config-management-system/sync-istions-clone # Get the status of the sync resource $ kpt alpha sync get sync-istions-clone -oyaml diff --git a/content/en/docs/release-notes/R3.md b/content/en/docs/release-notes/R3.md index 16cdf30d..15db8587 100644 --- a/content/en/docs/release-notes/R3.md +++ b/content/en/docs/release-notes/R3.md @@ -125,7 +125,7 @@ UI received dependency refresh, new Tabs component and security vulnerabilities * Better unit testing for rpkg commands, see https://github.com/nephio-project/porch/pull/33 * Porchctl rpkg commands now print to stdout on normal completion and stderr on errors, see https://github.com/nephio-project/porch/pull/30 * Porch Security Improvements - * Support for CA bundle TLS for git reporepository communications, see https://github.com/nephio-project/porch/pull/58 + * Support for CA bundle TLS for git repository communications, see https://github.com/nephio-project/porch/pull/58 * Configuration of an external webhook and associated certs for resource deletion is now supported https://github.com/nephio-project/porch/pull/53 * Missing repository RBAC roles for porch controllers were added, see https://github.com/nephio-project/porch/pull/56 * The porch namespace in the generated cert/webhook can now be configured https://github.com/nephio-project/porch/pull/26 From 6cbfdfa277d326abb43e91ed7d680ec0b11f4f8e Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 25 Oct 2024 11:55:21 +0300 Subject: [PATCH 46/74] Fix typo in Step by step guide to deploy the Free5gc Operator Signed-off-by: Gergely Csatari --- content/en/docs/guides/install-guides/explore-nephio-free5gc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md index 96890331..c5b4b378 100644 --- a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md +++ b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md @@ -33,7 +33,7 @@ tasks such as ## The structure of the repository 1. [Operator](https://github.com/nephio-project/free5gc/tree/main/free5gc-operator) - * Binding metrics and hcheck ports + * Binding metrics and check the health of ports * Registering UPF SMF AMF deployments * Reconciler and Setup (Creating Controllers) From 2bf0d66d867e55ef2cfff96197d68b193ce03308 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 25 Oct 2024 12:42:56 +0300 Subject: [PATCH 47/74] Making the vale job non blocking Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 053764df..5303e2a8 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -31,4 +31,5 @@ jobs: reporter: github-pr-check fail_on_error: false filter_mode: nofilter - token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file + token: ${{secrets.VALE_GITHUB_TOKEN}} + continue-on-error: true \ No newline at end of file From 7029741a1adba4ac1b2648cb012968c8a9029cc7 Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Fri, 25 Oct 2024 13:06:29 +0300 Subject: [PATCH 48/74] Fixing link and GitHub job config Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 2 +- content/en/docs/porch/package-orchestration.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index 5303e2a8..cb247ec3 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -24,6 +24,7 @@ jobs: env - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog + continue-on-error: true with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check @@ -32,4 +33,3 @@ jobs: fail_on_error: false filter_mode: nofilter token: ${{secrets.VALE_GITHUB_TOKEN}} - continue-on-error: true \ No newline at end of file diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index f1b6d512..748566c0 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -401,7 +401,7 @@ Orchestration service. ## User Guide -Find the Porch User Guide in a dedicated [document](using-porch/usage-porch-kpt-cli). +Find the Porch User Guide in a dedicated [document](using-porch/usage-porch-kpt-cli.md). ## Open Issues/Questions From 7f04cc126a3f0d28b9584a59c169c0f5a7d1fd53 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Mon, 4 Nov 2024 08:31:16 +0100 Subject: [PATCH 49/74] Language corrections for the R3 Release Notes. (#175) Signed-off-by: Michael Greaves --- content/en/docs/release-notes/R3.md | 173 +++++++++++++++------------- 1 file changed, 91 insertions(+), 82 deletions(-) diff --git a/content/en/docs/release-notes/R3.md b/content/en/docs/release-notes/R3.md index 25027f62..6d117041 100644 --- a/content/en/docs/release-notes/R3.md +++ b/content/en/docs/release-notes/R3.md @@ -5,130 +5,139 @@ weight: 1 ## Overview -The theme of R3 is “strengthen the platform ; get ready for O-RAN”. As such, a major focus in this release has been on improving the functional robustness, stability and usability of the Nephio core components. In addition, a significant effort has been put into improving the documentation and simplifying developer workflows, to ease onboarding of new developers into the Nephio community. A number of O-RAN user stories have been triaged in readiness for implementation in future releases. +The theme of R3 is the strengthening of the platform and preparation for O-RAN. As such, a key focus in this release has been on improving the functional robustness, stability, and usability of the Nephio core components. In addition, a significant effort has been made to improve the documentation and simplify developer workflows, to ease the onboarding of new developers into the Nephio community. A number of O-RAN user stories have been triaged in readiness for implementation in future releases. + ## Prerequisites -Please refer to the [Install Guide](/content/en/docs/guides/install-guides/install-on-byoc.md#prerequisites) -for the prerequisites on supported environments. +Refer to the [Install Guide](/content/en/docs/guides/install-guides/install-on-byoc.md#prerequisites) for the +prerequisites on supported environments. -## Support Matrix +## Support matrix -The sandbox environment requires a physical or virtual machine with: -- Ubuntu-20.04-focal or Ubuntu 22.04 Linux Or Fedora 34 -- Minimum 8 cores and Recommended 16 cores (Needed for end-to-end testing with RAN and core ) -- 32 GB memory -- 200 GB disk size -- Default user with sudo passwordless permissions +The sandbox environment requires a physical or virtual machine with the following: +- Ubuntu-20.04-focal or Ubuntu 22.04 Linux Or Fedora 34. +- A minimum of eight cores. 16 cores is the recommended quantity, however, as they are needed for end-to-end testing with RAN and core. +- 32 GB memory. +- 200 GB disk size. +- A default user with sudo passwordless permissions. -This installation has been verified on VMs running on Google Cloud. +This installation has been verified on virtual machines (VMs) running on Google Cloud. -A Nephio sandbox can be created on any Kubernetes cluster v1.26 and above. +A Nephio sandbox can be created on any Kubernetes cluster, from v1.26 onwards. ## Features ### API -No changes +No changes. ### Web UI -UI received dependency refresh, new Tabs component and security vulnerabilities fixes. +The UI has received a dependency refresh. A new Tabs component has been introduced, as well as fixes to security vulnerabilities. ### Packages -* Catalog fixes -* Packages to deploy OSC RIC +The following packages have been introduced: + +* Catalog fixes. +* Packages for deploying OSC RIC. ### Functionalities * Platform - * Fixes, Security patches and enhancements to Porch. See [Appendix](#appendix) for details. - * The Porch development environment is much improved, with a tutorial, script support, and makefile targets available. Developers can now - * Run Porch locally on Kind - * Run the Porch Server or Porch controllers in vscode towards a local Kind porch installation - * Run the end to end tests locally - * Work on Linux or MacOS locally or using a VM - * The Porch documentation was improved with the addition of a Porch tutorial, which steps the user through the main Porch use cases. Documentation on how to use Porchctl was also added - * The Porch build and test toolchain was heavily augmented. Among them was stepping the Go version to 1.22, adding Github actions to build the latest Porch and Porchctl images, support for running the Porch/Porchctl tests locally, and stepping the versions of various dependencies. - + * Fixes, security patches, and enhancements to Porch. See [Appendix](#appendix) for details. + * The Porch development environment has been improved, with a tutorial, script support, and makefile targets now available. Developers can now do the following: VSCode towards a local KIND porch installation. + * Run the end-to-end tests locally. + * Work on Linux or MacOS locally or using a VM. + * The Porch documentation has been improved with the addition of a Porch tutorial, which takes the user through the main Porch use cases. Documentation on how to use Porchctl has also been added. + * The Porch build and test toolchain has been augmented. The additions include the following: + * Upgrading the Go version to 1.22. + * Adding GitHub actions, to build the latest Porch and Porchctl images. + * Support for running the Porch/Porchctl tests locally. + * Upgrading the versions of various dependencies. + * Documentation - * Improvements in aesthetics and bug fixes - * Updated [Component Architecture](https://r3.docs.nephio.org/docs/architecture/) - * Updated [Schema Catalog](https://docs.nephio.org/docs/apis/) - * [User Stories](https://docs.nephio.org/docs/network-architecture/) related to O-RAN integration and Service Assurance - * Versioning support for documentation + * Improvements in esthetics and bug fixes. + * Updated [Component Architecture](https://r3.docs.nephio.org/docs/architecture/). + * Updated [Schema Catalog](https://docs.nephio.org/docs/apis/). + * [User Stories](https://docs.nephio.org/docs/network-architecture/) related to O-RAN integration and service assurance. + * Versioning support for documentation. * Nephio experimental - * [Ytt-declarative-configuration](https://github.com/nephio-experimental/ytt-declarative-configuration) added. This is a generic KPT Function that utilizes the power YTT to achieve higher-level intent automation, reducing complexities and costs associated with infrastructure provisioning. - This simplifies deployment and management for the operator by enabling YTT’s templating capabilities to configure network functions. - * [Tko](https://github.com/nephio-experimental/tko) is a self-contained playground for new ideas for Nephio’s future. It stores all data in a traditional SQL backend by default (including support for planetary-scale databases, such as Spanner), validates all KRM before allowing it to be stored in the backend, implements a minimalistic plugin system (included is an SDK for Python-based plugins as well as support for kpt functions), includes a topology plugin (with support for TOSCA) as well as native Helm support, and implements a more declarative specialization workflow. Also includes web and terminal UIs (TUI). - + * [Ytt-declarative-configuration](https://github.com/nephio-experimental/ytt-declarative-configuration) is a generic KPT function that uses the power YTT to achieve higher-level intent automation, reducing the complexities and costs associated with infrastructure provisioning. This simplifies the deployment and management for the operator by enabling YTT’s templating capabilities to configure the network functions. + * [Tko](https://github.com/nephio-experimental/tko) is a self-contained playground for new ideas for Nephio’s future. + * It stores all the data in a traditional SQL backend by default, including support for planetary-scale databases, such as Spanner. + * It validates the Kubernetes Resource Machine (KRM), before allowing it to be stored in the backend. + * It implements a minimalistic plugin system. An SDK for Python-based plugins is included, together with support for kpt functions. + * It includes a topology plugin, with support for TOSCA, as well as native Helm support. + * It implements a more declarative specialization workflow. + * It includes web and terminal user interfaces (TUIs). + * Security - * OpenSSF best practices score improved from 3.6 to 7.6 - * Release digital signing automation - * Vulnerability reporting process set in place + * The OpenSSF best practices score has improved from 3.6 to 7.6. + * Release digital signing automation. + * A vulnerability reporting process has been set in place. ### Fixes -* Porchctl development builds added -* Rpkg update panic is fixed -* Porch race condition is fixed -* High package approval time in the porch is fixed which should reduce the overall deployment time. -* Porch package revision fixes -* Porch connection failure with self-signed certificates is fixed -* Updated OAI RAN operator to reflect NFDeployment status - +* The Porchctl development builds have been added. +* The Rpkg update panic has been fixed. +* The Porch race condition has been fixed. +* High package approval time in Porch has been fixed. This should reduce the overall deployment time. +* Porch package revision fixes have been performed. +* Porch connection failure with self-signed certificates has been fixed. +* The OAI RAN operator has been updated to reflect the NFDeployment status. ## Limitations -* Inter-cluster networking is not dynamic so as more clusters are deployed, some manual tweaking will be needed for inter-cluster communications. -* Provisioning of VLAN interfaces on nodes is manual at this time. -* Feedback of workload deployments from workload clusters to the Management cluster is limited. You may need to connect directly to the Workload cluster via kubectl to debug any deployment issues. -* Web UI features are limited to view/edit of packages and resources in those packages and their deployment. Additional features will be added in subsequent releases. -* When the capacities of the UPF,SMF and AMF NFs are changed, the free5GC Operator on the Workload cluster will instantiate a new POD with correspondingly modified resources (CPU, memory etc.) During this process, the pod will restart. This is a limitation of free5GC. -* Only Gitea works with automated cluster provisioning to create new repositories and join them to Nephio. To use a different Git provider, you must manually provision cluster repositories, register them to the Nephio management server, and set up Config Sync on the Workload cluster. -* The WebUI does not require authentication in the current demo configuration. Testing of the WebUI with authentication configured has not been done at this time. -* The WebUI only shows resources in the default namespace. -* While many types of Git authentication are supported, the testing was only done with token-based Git authentication in Gitea. +* Intercluster networking is not dynamic. Therefore, as more clusters are deployed, some manual tweaking will be needed for intercluster communications. +* Provisioning of the VLAN interfaces on the nodes is currently performed manually. +* Feedback of the workload deployments from the workload clusters to the management cluster is limited. You may need to connect directly to the workload cluster via kubectl to resolve any deployment issues. +* The web UI features are limited to the viewing and editing of packages, and resources in those packages, and their deployment. Additional features will be added in subsequent releases. +* When the capacities of the UPF, SMF, and AMF NFs are changed, the free5GC operator on the workload cluster will instantiate a new POD with correspondingly modified resources (CPU, memory, and so on). During this process, the pod will restart. This is a limitation of free5GC. +* Only Gitea works with automated cluster provisioning to create new repositories and join them to Nephio. To use a different Git provider, you must manually provision the cluster repositories, register them to the Nephio management server, and set up Config Sync on the workload cluster. +* The web UI does not require authentication in the current demo configuration. Testing of the web UI with authentication configured has not yet been done. +* The web UI only shows the resources in the default namespace. +* While many types of Git authentication are supported, testing has only been done with token-based Git authentication in Gitea. +## Known issues and workarounds -## Known Issues and Workarounds +* Packages may take time to be approved by the auto-approval controller. If they appear to have frozen, it may help to restart the Porch and the Nephio controllers using the following commands: -* Packages may take a long time to be approved by the auto-approval - controller. If they seem stuck, restarting Porch and the Nephio controllers - may help: ```bash kubectl -n porch-system rollout restart deploy porch-server kubectl -n nephio-system rollout restart deploy nephio-controller ``` -* Occasional calls to `porchctl rpkg copy` may fail with a message like +* Occasional calls to `porchctl rpkg copy` may fail with the following message: + `Error: Internal error occurred: error applying patch: conflict: fragment line - does not match src line`. Try again in a little while, this may clear up on - its own. Restarting Porch may also help. + does not match src line`. + + If such a message appears, then retry in a little while, as this error may resolve itself. Restarting Porch may also help. ## Appendix -### Porch Fixes and enhancements - -* Functional Improvements to Porch including - * Using the default exponential back-off in case of errors instead of a constant 30 sec retry, see https://github.com/nephio-project/porch/pull/76 - * Showing kpt package rendering errors via the status of PackageVariant, see https://github.com/nephio-project/porch/pull/75 - * Support for new field selectors: spec.workspaceName and spec.lifecycle on PackageRevision resources, see https://github.com/nephio-project/porch/pull/70 - * Caching in the case of multiple Repository resources pointing to the same git repo is fixed, see https://github.com/nephio-project/porch/pull/68 - * The PackageRevision's metadata.uid field is now unique, see https://github.com/nephio-project/porch/pull/61 - * Caching for packageRevisionResources is removed, they should not have been cached, see https://github.com/nephio-project/porch/pull/55 - * Pod templating for function runner is introduced, see https://github.com/nephio-project/porch/pull/54 - * Garbage collection is updated to reclaim pods in namespace which contain only KRM functions, see https://github.com/nephio-project/porch/pull/52 -* Functional Improvements to Porchctl including: - * The porchctl version is now returned correctly, see https://github.com/nephio-project/porch/pull/65 - * The error message emitted when metadata is missing is now less confusing, see https://github.com/nephio-project/porch/pull/39 - * Better unit testing for rpkg commands, see https://github.com/nephio-project/porch/pull/33 - * Porchctl rpkg commands now print to stdout on normal completion and stderr on errors, see https://github.com/nephio-project/porch/pull/30 -* Porch Security Improvements - * TSupport for cabundle tls for git repo comms, see https://github.com/nephio-project/porch/pull/58 - * TConfiguration of an external webhook and associated certs for resource deletion is now supported https://github.com/nephio-project/porch/pull/53 - * TMissing repository RBAC roles for porch controllers were added, see https://github.com/nephio-project/porch/pull/56 - * TThe porch namespace in the generated cert/webhook can now be configured https://github.com/nephio-project/porch/pull/26 +### Porch fixes and enhancements + +* Functional improvements to Porch include the following: + * Using the default exponential back-off in case of errors, instead of a constant 30-second retry. For details, see https://github.com/nephio-project/porch/pull/76. + * Showing kpt package rendering errors via the status of PackageVariant. For details, see https://github.com/nephio-project/porch/pull/75. + * Support for new field selectors: spec.workspaceName and spec.lifecycle on PackageRevision resources. For details, see https://github.com/nephio-project/porch/pull/70. + * Caching in the case of multiple repository resources pointing to the same Git repository has been fixed. For details, see https://github.com/nephio-project/porch/pull/68. + * The PackageRevision's metadata.uid field is now unique. For details, see https://github.com/nephio-project/porch/pull/61. + * Caching for packageRevisionResources has been removed. They should not have been cached. For details, see https://github.com/nephio-project/porch/pull/55. + * Pod templating for the function runner has been introduced. For details, see https://github.com/nephio-project/porch/pull/54. + * Garbage collection has been updated to reclaim the pods in the namespace which contain only KRM functions. For details, see https://github.com/nephio-project/porch/pull/52. +* Functional improvements to Porchctl, including the following: + * The porchctl version has now been returned correctly. For details, see https://github.com/nephio-project/porch/pull/65. + * The error message that appears when the metadata is missing is now less confusing. For details, see https://github.com/nephio-project/porch/pull/39. + * Unit testing for rpkg commands has been improved. For details, see https://github.com/nephio-project/porch/pull/33. + * Porchctl rpkg commands now print to stdout on normal completion and stderr on errors. For details, see https://github.com/nephio-project/porch/pull/30. +* Porch security improvements: + * Support for CA bundle for verification of TLS for Git repository commits. For details, see https://github.com/nephio-project/porch/pull/58. + * Configuration of an external webhook and associated certs for resource deletion is now supported. For details, see https://github.com/nephio-project/porch/pull/53. + * Missing repository RBAC roles for porch controllers have been added. For details, see https://github.com/nephio-project/porch/pull/56. + * The Porch namespace in the generated cert/webhook can now be configured. For details, see https://github.com/nephio-project/porch/pull/26. From ee64b566f0a8325dab01fbe254d54a9cec87a215 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Thu, 7 Nov 2024 10:53:18 +0000 Subject: [PATCH 50/74] Adding Porch private authenticated registries functionality documentation (#178) Paired with PR [#126](https://github.com/nephio-project/porch/pull/126) This provides documentation on how to configure porch to use external private authenticated registries. --- .../using-authenticated-private-registries.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 content/en/docs/porch/using-porch/using-authenticated-private-registries.md diff --git a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md new file mode 100644 index 00000000..c0b7257e --- /dev/null +++ b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md @@ -0,0 +1,92 @@ +--- +title: "Using authenticated private registries" +type: docs +weight: 4 +description: "" +--- + +To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: + +1. Creating a kubernetes secret using a JSON file according to the Docker config schema, containing valid credentials for each authenticated registry. +2. Mounting this new secret as a volume on the function runner. +3. Providing the path of the mounted secret to the function runner using the argument `--registry-auth-secret-path` + +An example template of what a docker *config.json* file looks like is as follows below. The base64 encoded value *bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=* of the *auth* key decodes to *my_username:my_password*, which is the format used by the config when authenticating. + +```json +{ + "auths": { + "https://index.docker.io/v1/": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + }, + "ghcr.io": { + "auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=" + } + } +} +``` + +A quick way to generate this secret for your use using your docker *config.json* would be to run the following command: + +```bash +kubectl create secret generic --from-file=.dockerconfigjson=/path/to/your/config.json --type=kubernetes.io/dockerconfigjson --dry-run=client -o yaml -n porch-system +``` + +{{% alert title="Note" color="primary" %}} +The secret must be in the same namespace as the function runner deployment. By default, this is the *porch-system* namespace. +{{% /alert %}} + +This should generate a secret template, similar to the one below, which you can add to the *2-function-runner.yaml* file in the Porch catalog package found [here](https://github.com/nephio-project/catalog/tree/main/nephio/core/porch) + +```yaml +apiVersion: v1 +data: + .dockerconfigjson: +kind: Secret +metadata: + creationTimestamp: null + name: + namespace: porch-system +type: kubernetes.io/dockerconfigjson +``` + +Next you must mount the secret as a volume on the function runner deployment. Add the following snippet to the Deployment object in the *2-function-runner.yaml* file: + +```yaml + volumeMounts: + - mountPath: /pod-cache-config + name: pod-cache-config-volume + - mountPath: /var/tmp/auth-secret + name: docker-config + readOnly: true +volumes: + - name: pod-cache-config-volume + configMap: + name: pod-cache-config + - name: docker-config + secret: + secretName: +``` + +You may specify your desired `mountPath:` so long as the function runner can access it. + +{{% alert title="Note" color="primary" %}} +The chosen `mountPath:` should use its own, dedicated sub-directory, so that it does not overwrite access permissions of the existing directory. For example, if you wish to mount on `/var/tmp` you should use `mountPath: /var/tmp/` etc. +{{% /alert %}} + +Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: + +```yaml +command: + - /server + - --config=/config.yaml + - --enable-private-registry=true + - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson + - --registry-auth-secret-name= + - --functions=/functions + - --pod-namespace=porch-fn-system +``` + +The `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments have default values of *false*, */var/tmp/auth-secret/.dockerconfigjson* and *auth-secret* respectively; however, these should be overridden to enable the functionality and match user specifications. + +With this last step, if your Porch package uses a custom kpt function image stored in an authenticated private registry (for example `- image: ghcr.io/private-registry/set-namespace:customv2`), the function runner will now use the secret info to replicate your secret on the `porch-fn-system` namespace and specify it as an `imagePullSecret` for the function pods, as documented [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). From 9127211736228112f286791460c399265b2b38ff Mon Sep 17 00:00:00 2001 From: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Date: Thu, 7 Nov 2024 11:07:19 +0000 Subject: [PATCH 51/74] Instructions on Porch Tracing setup added to Porch contributor guide (#181) Co-authored-by: JamesMcDermott Co-authored-by: Gergely Csatari --- .../contributors-guide/environment-setup.md | 71 +++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 3e86ea77..5d1e6ad9 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -179,3 +179,74 @@ and running the [setup script](https://github.com/nephio-project/porch/blob/main You can find a detailed description of the actual development process [here](dev-process.md). +## Enabling Open Telemetry/Jaeger tracing + +### Enabling tracing on a Porch deployment + +Follow the steps below to enable Open Telemetry/Jaeger tracing on your Porch deployment. + +1. Apply the Porch *deployment.yaml* manifest for Jaeger. + +```bash +kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/refs/heads/main/deployments/tracing/deployment.yaml +``` + +2. Add the environment variable *OTEL* to the porch-server manifest: + +```bash +kubectl edit deployment -n porch-system porch-server +``` + +```bash +env: +- name: OTEL + value: otel://jaeger-oltp:4317 +``` + +3. Set up port forwarding of the Jaeger http port to your local machine: + +```bash +kubectl port-forward -n porch-system service/jaeger-http 16686 +``` + +4. Open the Jaeger UI in your browser at *http://localhost:16686* + +### Enable tracing on a local Porch server + +Follow the steps below to enable Open Telemetry/Jaeger tracing on a porch server running locally on your machine, such as in VS Code. + +1. Download the Jaeger binary tarball for your local machine architecture from [the Jaeger download page](https://www.jaegertracing.io/download/#binaries) and untar the tarball in some suitable directory. + +2. Run Jaeger: + +```bash +cd jaeger +./jaeger-all-in-one +``` + +3. Configure the Porch server to output Open Telemetry traces: + + Set the *OTEL* environment variable to point at the Jaeger server + + In *.vscode/launch.json*: + +```bash +"env": { + ... + ... +"OTEL": "otel://localhost:4317", + ... + ... +} +``` + + In a shell: + +```bash +export OTEL="otel://localhost:4317" +``` + +4. Open the Jaeger UI in your browser at *http://localhost:16686* + +5. Run the Porch Server. + From 2d03550cef38705df7c99cf4a76e77fc5fe117aa Mon Sep 17 00:00:00 2001 From: Gergely Csatari Date: Thu, 14 Nov 2024 15:52:23 +0200 Subject: [PATCH 52/74] Making vale optional Signed-off-by: Gergely Csatari --- .github/workflows/proofreading-vale.yml | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/.github/workflows/proofreading-vale.yml b/.github/workflows/proofreading-vale.yml index d8500118..de07c0cb 100644 --- a/.github/workflows/proofreading-vale.yml +++ b/.github/workflows/proofreading-vale.yml @@ -1,10 +1,11 @@ name: reviewdog on: - pull_request_target: - types: [assigned, opened, edited, ready_for_review] - + pull_request: workflow_dispatch: +env: + REVIEWDOG_GITHUB_API_TOKEN: ${{secrets.VALE_GITHUB_TOKEN}} + jobs: vale: name: runner / vale @@ -13,19 +14,22 @@ jobs: - name: Checkout uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - - name: Harden Runner uses: step-security/harden-runner@91182cccc01eb5e619899d80e4e971d6181294a7 # v2.10.1 with: egress-policy: audit - - + - name: Install prerequisites + run: | + sudo apt-get --allow-releaseinfo-change update -y && sudo apt-get install -y docutils + env - name: Run Vale uses: errata-ai/vale-action@91ac403e8d26f5aa1b3feaa86ca63065936a85b6 # reviewdog - env: - REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.VALE_GITHUB_TOKEN }} + continue-on-error: true with: files: '["content", "README.md"]' # github-pr-check, github-pr-review, github-check + # more info on these: https://github.com/reviewdog/reviewdog#reporters reporter: github-pr-check + fail_on_error: false + filter_mode: nofilter token: ${{secrets.VALE_GITHUB_TOKEN}} \ No newline at end of file From 0fb0d200140085a24f574b9490d45aff959c2ac4 Mon Sep 17 00:00:00 2001 From: Schweier Dominika Date: Thu, 14 Nov 2024 19:39:37 +0100 Subject: [PATCH 53/74] Correcting identifiers (#179) Correcting identifiers to follow the guide "Do not surround IP addresses, domain names or any other identifyers with backticks. Use italics (* *) to mark any inline IP address, domain name, file name, file location or similar." https://docs.nephio.org/docs/guides/contributor-guides/documentation/ --------- Signed-off-by: Dominika Schweier Signed-off-by: Gergely Csatari Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Co-authored-by: Gergely Csatari --- .linkspector.yml | 3 + content/en/docs/_index.md | 1 + ...to-operator-codegen-sdk-developer-guide.md | 17 +- .../contributor-guides/minimal-environment.md | 4 +- .../unit-testing-mockery.md | 34 +- .../en/docs/guides/install-guides/_index.md | 10 +- .../install-guides/common-components.md | 10 +- .../install-guides/common-dependencies.md | 4 +- .../install-guides/demo-vagrant-windows.md | 6 +- .../install-guides/explore-nephio-free5gc.md | 24 +- .../guides/install-guides/explore-sandbox.md | 34 +- .../guides/install-guides/install-on-byoc.md | 24 +- .../guides/install-guides/install-on-gce.md | 4 +- .../guides/install-guides/install-on-gcp.md | 74 +-- .../install-guides/install-on-multiple-vm.md | 30 +- .../install-guides/install-on-openshift.md | 6 +- .../install-guides/install-on-single-vm.md | 26 +- .../install-guides/package-transformations.md | 240 +++++----- .../guides/install-guides/webui-auth-gcp.md | 22 +- .../guides/install-guides/webui-auth-okta.md | 26 +- .../en/docs/guides/install-guides/webui.md | 18 +- .../en/docs/guides/user-guides/controllers.md | 6 +- .../guides/user-guides/exercise-1-free5gc.md | 62 +-- .../docs/guides/user-guides/exercise-2-oai.md | 42 +- .../docs/guides/user-guides/helm/flux-helm.md | 16 +- ...helm-to-operator-codegen-sdk-user-guide.md | 4 +- .../network-architecture/o-ran-integration.md | 2 +- content/en/docs/porch/config-as-data.md | 16 +- .../docs/porch/contributors-guide/_index.md | 36 +- .../porch/contributors-guide/dev-process.md | 16 +- .../environment-setup-vm.md | 16 +- .../contributors-guide/environment-setup.md | 22 +- .../en/docs/porch/package-orchestration.md | 140 +++--- content/en/docs/porch/package-variant.md | 438 +++++++++--------- .../porch/running-porch/running-locally.md | 8 +- .../porch/running-porch/running-on-GKE.md | 28 +- .../adding-external-git-ca-bundle.md | 12 +- .../using-porch/install-and-using-porch.md | 146 +++--- .../porch/using-porch/porchctl-cli-guide.md | 4 +- .../porch/using-porch/usage-porch-kpt-cli.md | 86 ++-- 40 files changed, 858 insertions(+), 859 deletions(-) diff --git a/.linkspector.yml b/.linkspector.yml index 00e62e46..ab397a04 100644 --- a/.linkspector.yml +++ b/.linkspector.yml @@ -11,6 +11,9 @@ ignorePatterns: - pattern: "^http://localhost.*$" - pattern: "^http://HOSTNAME:PORT.*$" - pattern: "172\\.18\\.255\\.200" + - pattern: "https://\\*kpt\\*\\.dev/" + - pattern: "https://my-gitlab\\.com/joe\\.bloggs/blueprints\\.git" + - pattern: "http://172\\.18\\.0\\.200:3000/nephio/" replacementPatterns: - pattern: ".md#.*$" replacement: ".md" diff --git a/content/en/docs/_index.md b/content/en/docs/_index.md index 5b7601e3..a2c79e3a 100644 --- a/content/en/docs/_index.md +++ b/content/en/docs/_index.md @@ -93,3 +93,4 @@ demonstration purposes, the same principles and code can be used for managing other infrastructure and network functions. The *uniformity in systems* principle means that as long as something is manageable via the Kubernetes Resource Model, it is manageable via Nephio. + diff --git a/content/en/docs/guides/contributor-guides/helm-to-operator-codegen-sdk-developer-guide.md b/content/en/docs/guides/contributor-guides/helm-to-operator-codegen-sdk-developer-guide.md index df56eafd..85209bec 100644 --- a/content/en/docs/guides/contributor-guides/helm-to-operator-codegen-sdk-developer-guide.md +++ b/content/en/docs/guides/contributor-guides/helm-to-operator-codegen-sdk-developer-guide.md @@ -6,7 +6,7 @@ weight: 1 The [Helm to Operator Codegen SDK](https://github.com/nephio-project/nephio-sdk/tree/main/helm-to-operator-codegen-sdk) offers a streamlined solution for translating existing Helm charts into Kubernetes operators with minimal effort and cost. ## The Flow Diagram -In a nutshell, the Helm-Charts are converted to YAML files using the values provided in "values.yaml". Then, each Kubernetes Resource Model (KRM) in the YAML is translated into Go code, employing one of two methods. +In a nutshell, the Helm-Charts are converted to YAML files using the values provided in *values.yaml*. Then, each Kubernetes Resource Model (KRM) in the YAML is translated into Go code, employing one of two methods. 1) If the resource is Runtime-Supported, it undergoes a conversion process where the KRM resource is first transformed into a Runtime Object, then into JSON, and finally into Go code. 2) Otherwise, if the resource is not Runtime-Supported, it is converted into an Unstructured Object and then into Go code. @@ -20,7 +20,7 @@ Helm to YAML conversion is achieved by running the following command `helm template --namespace --output-dir “temp/templated/”` internally. As of now, it retrieves the values from default "values.yaml" ### Flow-2: YAML Split -The SDK iterates over each YAML file in the "converted-yamls" directory. If a YAML file contains multiple Kubernetes Resource Models (KRM), separated by "---", the SDK splits the YAML file accordingly to isolate each individual KRM resource. This ensures that each KRM resource is processed independently. +The SDK iterates over each YAML file in the *converted-yamls* directory. If a .yaml file contains multiple Kubernetes Resource Models (KRM), separated by "---", the SDK splits the .yaml file accordingly to isolate each individual KRM resource. This ensures that each KRM resource is processed independently. ### Runtime-Object and Unstruct-Object The SDK currently employs the "runtime-object method" to handle Kubernetes resources whose structure is recognized by Kubernetes by default. Examples of such resources include Deployment, Service, and ConfigMap. Conversely, resources that are not inherently known to Kubernetes and require explicit installation or definition, such as Third-Party Custom Resource Definitions (CRDs) like NetworkAttachmentDefinition or PrometheusRule, are processed using the "unstructured-object" method. Such examples are given below: @@ -69,15 +69,14 @@ networkAttachmentDefinition1 := &unstructured.Unstructured{ ``` ### Flow-3.1: KRM to Runtime-Object -The conversion process relies on the "k8s.io/apimachinery/pkg/runtime" package. Currently, only the API version "v1" is supported. The supported kinds for the Runtime Object method include: -`Deployment, Service, Secret, Role, RoleBinding, ClusterRoleBinding, PersistentVolumeClaim, StatefulSet, ServiceAccount, ClusterRole, PriorityClass, ConfigMap` +The conversion process relies on the "k8s.io/apimachinery/pkg/runtime" package. Currently, only the API version "v1" is supported. The supported kinds for the Runtime Object method include: Deployment, Service, Secret, Role, RoleBinding, ClusterRoleBinding, PersistentVolumeClaim, StatefulSet, ServiceAccount, ClusterRole, PriorityClass, ConfigMap ### Flow-3.2: Runtime-Object to JSON Firstly, the SDK performs a typecast of the runtime object to its actual data type. For instance, if the Kubernetes Kind is "Service," the SDK typecasts the runtime object to the specific data type corev1.Service. Then, it conducts a Depth-First Search (DFS) traversal over the corev1.Service object using reflection. During this traversal, the SDK generates a JSON structure that encapsulates information about the struct hierarchy, including corresponding data types and values. This transformation results in a JSON representation of the corev1.Service object's structure and content. #### DFS Algorithm Cases -The DFS function iterates over the runtime object, traversing its structure in a Depth-First Search manner. During this traversal, it constructs the JSON structure while inspecting each attribute for its data type and value. Attributes that have default values in the runtime object but are not explicitly set in the YAML file are omitted from the conversion process. This ensures that only explicitly defined attributes with their corresponding values are included in the resulting JSON structure. The function follows this flow to accurately capture the structure, data types, and values of the Kubernetes resource while excluding default attributes that are not explicitly configured in the YAML file. +The DFS function iterates over the runtime object, traversing its structure in a Depth-First Search manner. During this traversal, it constructs the JSON structure while inspecting each attribute for its data type and value. Attributes that have default values in the runtime object but are not explicitly set in the .yaml file are omitted from the conversion process. This ensures that only explicitly defined attributes with their corresponding values are included in the resulting JSON structure. The function follows this flow to accurately capture the structure, data types, and values of the Kubernetes resource while excluding default attributes that are not explicitly configured in the .yaml file. A) Base-Cases: @@ -156,7 +155,7 @@ spec: ``` ### Flow-3.3: JSON to String (Go-Code) -The SDK reads the JSON file containing the information about the Kubernetes resource and then translates this information into a string of Go code. This process involves parsing the JSON structure and generating corresponding Go code strings based on the structure, data types, and values extracted from the JSON representation. Ultimately, this results in a string that represents the Kubernetes resource in a format compatible with Go code. +The SDK reads the .json file containing the information about the Kubernetes resource and then translates this information into a string of Go code. This process involves parsing the JSON structure and generating corresponding Go code strings based on the structure, data types, and values extracted from the JSON representation. Ultimately, this results in a string that represents the Kubernetes resource in a format compatible with Go code. #### TraverseJSON Cases (Json-to-String) The traverse JSON function is responsible for converting JSON data into Go code. Here's how it handles base cases: @@ -275,12 +274,12 @@ Structs need to be initialized using curly brackets {}, whereas enums need Paren Solution: We solve the above problems by building an “enumModuleMapping” which is a set that stores all data types that are enums. i.e. If a data type belongs to the set, then It is an Enum. -There is an automation-script that takes the types.go files of packages and build the config-json. For details, Please refer [here](https://github.com/nephio-project/nephio-sdk/tree/main/helm-to-operator-codegen-sdk/config) +There is an automation-script that takes the *types.go* files of packages and build the config-json. For details, Please refer [here](https://github.com/nephio-project/nephio-sdk/tree/main/helm-to-operator-codegen-sdk/config) ### Flow-4: KRM to Unstruct-Obj to String(Go-code) -All Kubernetes resource kinds that are not supported by the runtime-object method are handled using the unstructured method. In this approach, the Kubernetes Resource MOdel (KRM) is converted to an unstructured object using the package "k8s.io/apimachinery/pkg/apis/meta/v1/unstructured". -Then, We traverse the unstructured-Obj in a DFS fashion and build the gocode-string. +All Kubernetes resource kinds that are not supported by the runtime-object method are handled using the unstructured method. In this approach, the Kubernetes Resource MOdel (KRM) is converted to an unstructured object using the package *k8s.io/apimachinery/pkg/apis/meta/v1/unstructured*"*. +Then, we traverse the unstructured-Obj in a DFS fashion and build the gocode-string. #### DFS Algorithm Cases (Unstruct-Version) diff --git a/content/en/docs/guides/contributor-guides/minimal-environment.md b/content/en/docs/guides/contributor-guides/minimal-environment.md index cf762bca..94159f8b 100644 --- a/content/en/docs/guides/contributor-guides/minimal-environment.md +++ b/content/en/docs/guides/contributor-guides/minimal-environment.md @@ -106,11 +106,11 @@ Connecting to Gitea allows you to see the actions that Nephio takes on Gitea. kubectl port-forward -n gitea svc/gitea 3000:3000 ``` -2. Browse to the Gitea web client at `http://localhost:3000` and log on. +2. Browse to the Gitea web client at http://localhost:3000 and log on. ## VS Code Configuration -Set up a launch configuration in VS Code `launch.json` similar to the configuration below: +Set up a launch configuration in VS Code *launch.json* similar to the configuration below: ```json { diff --git a/content/en/docs/guides/contributor-guides/unit-testing-mockery.md b/content/en/docs/guides/contributor-guides/unit-testing-mockery.md index 8f745362..8df5f8ec 100644 --- a/content/en/docs/guides/contributor-guides/unit-testing-mockery.md +++ b/content/en/docs/guides/contributor-guides/unit-testing-mockery.md @@ -10,11 +10,11 @@ This guide will help folks come up to speed on using testify and mockery. ## How Mockery works -The [mockery documentation](https://vektra.github.io/mockery/latest/#why-mockery) describes why you would use and how to use Mockery. In a nutshell, Mockery generates mock implementations for interfaces in `go`, which you can then use instead of real implementations when unit testing. +The [mockery documentation](https://vektra.github.io/mockery/latest/#why-mockery) describes why you would use and how to use Mockery. In a nutshell, Mockery generates mock implementations for interfaces in go, which you can then use instead of real implementations when unit testing. ## Mockery support in Nephio `make` -The `make` files in Nephio repos containing `go` code have targets to support mockery. +The `make` files in Nephio repos containing go code have targets to support mockery. The [default-mockery.mk](https://github.com/nephio-project/nephio/blob/main/default-mockery.mk) file in the root of Nephio repos is included in Nephio `make` runs. @@ -27,13 +27,13 @@ The targets above must be run explicitly. Run `make install-mockery` to install mockery in your container runtime (docker, podman etc) or locally if you have no container runtime running. You need only run this target once unless you need to reinstall Mockery for whatever reason. -Run `make generate-mocks` to generate the mocked implementation of the go interfaces specified in '.mockery.yaml' files. You need to run this target each time an interface that you are mocking changes or whenever you change the contents of a `.mockery.yaml` file. You can run `make generate-mocks` in the repo root to generate or re-generate all interfaces or in subdirectories containing a `Makefile` to generate or regenerate only the interfaces in that subdirectory and its children. +Run `make generate-mocks` to generate the mocked implementation of the go interfaces specified in *.mockery.yaml* files. You need to run this target each time an interface that you are mocking changes or whenever you change the contents of a *.mockery.yaml* file. You can run `make generate-mocks` in the repo root to generate or re-generate all interfaces or in subdirectories containing a Makefile to generate or regenerate only the interfaces in that subdirectory and its children. -The generate-mocks target looks for `.mockery.yaml` files in the repo and it runs the mockery mock generator on each `.mockery.yaml` file it finds. This has the nice effect of allowing `.mockery.yaml` files to be in either the root of the repo or in subdirectories, so the choice of placement of `.mockery.yaml` files is left to the developer. +The generate-mocks target looks for *.mockery.yaml`* files in the repo and it runs the mockery mock generator on each *.mockery.yaml* file it finds. This has the nice effect of allowing *.mockery.yaml* files to be in either the root of the repo or in subdirectories, so the choice of placement of *.mockery.yaml* files is left to the developer. ## The .mockery.yaml file -The `.mockery.yaml` file specifies which mock implementations Mockery should generate and also controls how that generation is performed. Here we just give an overview of `mockery.yaml`. For full details consult the [configuration](https://github.com/vektra/mockery/blob/master/docs/configuration.md) section of the Mockery documentation. +The *.mockery.yaml* file specifies which mock implementations Mockery should generate and also controls how that generation is performed. Here we just give an overview of *mockery.yaml*. For full details consult the [configuration](https://github.com/vektra/mockery/blob/master/docs/configuration.md) section of the Mockery documentation. ### Example 1 @@ -53,7 +53,7 @@ We provide a list of the packages for which we want to generate mocks. In this e 6. dir: "{{.InterfaceDir}}" ``` -We want mocks to be generated for the `GiteaClient` go interface (line 4). The `{{.InterfaceDir}}` parameter (line 6) asks Mockery to generate the mock file in the same directory as the interface is located. +We want mocks to be generated for the GiteaClient go interface (line 4). The {{.InterfaceDir}} parameter (line 6) asks Mockery to generate the mock file in the same directory as the interface is located. ### Example 2 @@ -80,14 +80,14 @@ Lines 2 to 7 are as explained in Example 1 above. 8. sigs.k8s.io/controller-runtime/pkg/client: ``` -Generate mocks for the external package `sigs.k8s.io/controller-runtime/pkg/client`. +Generate mocks for the external package *sigs.k8s.io/controller-runtime/pkg/client*. ``` 9. interfaces: 10. Client: ``` -Generate a mock implementation of the go interface `Client` in the external package `sigs.k8s.io/controller-runtime/pkg/client`. +Generate a mock implementation of the go interface Client in the external package *sigs.k8s.io/controller-runtime/pkg/client*. ``` 11. config: @@ -95,7 +95,7 @@ Generate a mock implementation of the go interface `Client` in the external pack 13. outpkg: "mocks" ``` -Create the mocks for the `Client` interface in the `mocks/external/client` directory and cal the output package `mocks`. +Create the mocks for the Client interface in the *mocks/external/client* directory and cal the output package *mocks*. ## The generated mock implementation @@ -107,7 +107,7 @@ We can treat this generated file as a black box and we do not have to know the d The [mockery utils](https://github.com/nephio-project/nephio/tree/main/testing/mockeryutils) package is a utility package that you can use to initialize your mocks and to define some common fields for your tests. -[mockeryutils-types.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the `MockHelper` struct, which allows you to control the behaviour of a mock. +[mockeryutils-types.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the MockHelper struct, which allows you to control the behaviour of a mock. ``` type MockHelper struct { @@ -117,15 +117,15 @@ type MockHelper struct { } ``` -The `MockHelper` struct is used to configure a mocked method to expect and return a certain set of arguments. We pass instances of this struct to the mocked interface during tests. +The MockHelper struct is used to configure a mocked method to expect and return a certain set of arguments. We pass instances of this struct to the mocked interface during tests. -[mockeryutils.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the `InitMocks` function, which initializes your mocks for you before a test. +[mockeryutils.go](https://github.com/nephio-project/nephio/blob/main/testing/mockeryutils/mockeryutils-types.go) contains the InitMocks function, which initializes your mocks for you before a test. ``` func InitMocks(mocked *mock.Mock, mocks []MockHelper) ``` -For the given `mocked` interface, the function initializes the `mocks` as specified in the given `MockHelper` array. +For the given mocked interface, the function initializes the mocks as specified in the given MockHelper array. ## Using the mock implementation in unit tests @@ -151,7 +151,7 @@ type repoTest struct { wantErr bool } ``` -The code above allows us to specify input data and the expected outcome for tests. Each test is specified as an instance of the `repoTest` struct. For each test, we specify its fields and arguments, and specify the mocking for the test. +The code above allows us to specify input data and the expected outcome for tests. Each test is specified as an instance of the repoTest struct. For each test, we specify its fields and arguments, and specify the mocking for the test. ``` func TestUpsertRepo(t *testing.T) @@ -194,7 +194,7 @@ This is the specification of an array of tests that we will run. } ``` -The code above specifies a single test and is an instance of the `tests` array. We specify the fields, arguments, and mocks for the test. In this case, we mock three functions on our GiteaClient interface: `GetMyUserInfo`, `GetRepo`, and `CreateRepo`. We specify the arguments we expect for each function and specify what the function should return if it receives correct arguments. Of course, if the mocked function receives incorrect arguments, it will report an error. The `wantErr` value indicates if we expect the `upsertRepo` function being tested to succeed or fail. +The code above specifies a single test and is an instance of the tests array. We specify the fields, arguments, and mocks for the test. In this case, we mock three functions on our GiteaClient interface: GetMyUserInfo, GetRepo, and CreateRepo. We specify the arguments we expect for each function and specify what the function should return if it receives correct arguments. Of course, if the mocked function receives incorrect arguments, it will report an error. The wantErr value indicates if we expect the upsertRepo function being tested to succeed or fail. ``` for _, tt := range tests { @@ -214,7 +214,7 @@ for _, tt := range tests { } ``` -The code above executes the tests. We run a reconciler `r` and initialize our tests using the local `initMockeryTests()` function. We then call the `upsertRepo` function to test it and check the result. +The code above executes the tests. We run a reconciler `r` and initialize our tests using the local initMockeryTests() function. We then call the upsertRepo function to test it and check the result. ``` func initMockeryMocks(tt *repoTest) { @@ -225,4 +225,4 @@ func initMockeryMocks(tt *repoTest) { } ``` -The `initMockeryMocks` local function calls the `mockeryutils.InitMocks` to initialize the mocks for the tests. +The initMockeryMocks local function calls the mockeryutils.InitMocks to initialize the mocks for the tests. diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md index 872bf863..ee8cc939 100644 --- a/content/en/docs/guides/install-guides/_index.md +++ b/content/en/docs/guides/install-guides/_index.md @@ -18,7 +18,7 @@ will be used in the exercises to simulate a topology with a Nephio management cl ### GCE Prerequisites -You will need a account in GCP and `gcloud` installed on your local environment. +You will need a account in GCP and *gcloud* installed on your local environment. ### Create a Virtual Machine on GCE @@ -65,7 +65,7 @@ Order or create a VM with the following specification: In some installations, the IP range used by Kubernetes in the sandbox can clash with the IP address used by your VPN. In such cases, the VM will become unreachable during the sandbox installation. If you have this situation, add the route below on your VM. -Log onto your VM and run the following commands, replacing **\** and **\** with your VMs values: +Log onto your VM and run the following commands, replacing *\* and *\* with your VMs values: ```bash sudo bash -c 'cat << EOF > /etc/netplan/99-cloud-init-network.yaml @@ -100,8 +100,8 @@ sudo NEPHIO_DEBUG=false \ **Pre-installed K8s Cluster** Log onto your VM/System and run the following command: -(NOTE: The VM or System should be able to access the K8S API server via the kubeconfig file and have docker installed. -Docker is needed to run the KRM container functions specified in rootsync and repository packages.) +(Note that the VM or System should be able to access the K8S API server via the *kubeconfig* file and have docker installed. +Docker is needed to run the KRM container functions specified in *rootsync* and *repository* packages.) ```bash wget -O - https://raw.githubusercontent.com/nephio-project/test-infra/v3.0.0/e2e/provision/init.sh | \ @@ -127,7 +127,7 @@ The following environment variables can be used to configure the installation: | NEPHIO_REPO | URL | https://github.com/nephio-project/test-infra.git | URL of the repository to be used for installation | | NEPHIO_BRANCH | branch | main/v3.0.0 | Tag or branch name to use in NEPHIO_REPO | | DOCKER_REGISTRY_MIRRORS | list of URLs in JSON format | | List of docker registry mirrors in JSON format, or empty for no mirrors to be set. Example value: ``["https://docker-registry-remote.mycompany.com", "https://docker-registry-remote2.mycompany.com"]`` | -| K8S_CONTEXT | K8s context | kind-kind | Kubernetes context for existing non-kind cluster (gathered from `kubectl config get-contexts`, for example "kubernetes-admin@kubernetes") | +| K8S_CONTEXT | K8s context | kind-kind | Kubernetes context for existing non-kind cluster (gathered from `kubectl config get-contexts`, for example *kubernetes-admin@kubernetes*) | ### Follow the Installation on VM diff --git a/content/en/docs/guides/install-guides/common-components.md b/content/en/docs/guides/install-guides/common-components.md index 0f739640..33ebb510 100644 --- a/content/en/docs/guides/install-guides/common-components.md +++ b/content/en/docs/guides/install-guides/common-components.md @@ -14,7 +14,7 @@ This page is draft and the separation of the content to different categories is {{% alert title="Note" color="primary" %}} -If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repo, then replace the `@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. +If you want to use a version other than that of v3.0.0 of Nephio *catalog* repo, then replace the *@origin/v3.0.0* suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a git repository. By default it pulls the tag. In case, you have branch with the same name as a tag then to: @@ -60,10 +60,10 @@ To install the Nephio Operators, repeat the `kpt` steps, but for that package: kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/nephio-operator@origin/v3.0.0 ``` -The Nephio Operator package by default uses the Gitea instance at `172.18.0.200:3000` as +The Nephio Operator package by default uses the Gitea instance at *172.18.0.200:3000* as the git repository. Change it to point to your git instance in -`nephio-operator/app/controller/deployment-token-controller.yaml` and -`nephio-operator/app/controller/deployment-controller.yaml` +*nephio-operator/app/controller/deployment-token-controller.yaml* and +*nephio-operator/app/controller/deployment-controller.yaml*. You also need to create a secret with your Git instance credentials: @@ -98,7 +98,7 @@ is used extensively in the cluster provisioning workflows. Different GitOps tools may be used, but these instructions only cover ConfigSync. To install it on the management cluster, we again follow the same process. -Later, we will configure it to point to the `mgmt` repository: +Later, we will configure it to point to the *mgmt* repository: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@origin/v3.0.0 diff --git a/content/en/docs/guides/install-guides/common-dependencies.md b/content/en/docs/guides/install-guides/common-dependencies.md index 851a9823..316e8051 100644 --- a/content/en/docs/guides/install-guides/common-dependencies.md +++ b/content/en/docs/guides/install-guides/common-dependencies.md @@ -12,7 +12,7 @@ installation, the CRDs that come along with them are necessary. {{% alert title="Note" color="primary" %}} -If you want to use a version other than that of `v3.0.0` of Nephio `catalog` repo, then replace the `@origin/v3.0.0` suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. +If you want to use a version other than that of v3.0.0 of Nephio *catalog* repo, then replace the *@origin/v3.0.0* suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a git repository. By default it pulls the tag. In case, you have branch with the same name as a tag then to: @@ -62,4 +62,4 @@ kpt live apply gitea --reconcile-timeout 15m --output=table ``` You can find the Gitea ip-address via `kubectl get svc -n gitea` -and use port `3000` to access it with login `nephio` and password `secret`. +and use port 3000 to access it with login *nephio* and password *secret*. diff --git a/content/en/docs/guides/install-guides/demo-vagrant-windows.md b/content/en/docs/guides/install-guides/demo-vagrant-windows.md index 87cc3e6b..f4e5d183 100644 --- a/content/en/docs/guides/install-guides/demo-vagrant-windows.md +++ b/content/en/docs/guides/install-guides/demo-vagrant-windows.md @@ -51,10 +51,10 @@ the Vagrant file. This is not recommended! {{% /alert %}} -- In the Vagrant file "./Vagrantfile", there are *CPUS & RAM* parameters in - `config.vm.provider`, it's possible to override them at runtime: +- In the Vagrant file *./Vagrantfile*, there are *CPUS & RAM* parameters in + the *config.vm.provider*, it's possible to override them at runtime: - On Linux, or the Git Bash on Windows we can use a one-liner command `CPUS=16 MEMORY=32768 vagrant up` -- In the Ansible "./playbooks/roles/bootstrap/tasks/prechecks.yml" file, there +- In the Ansible *./playbooks/roles/bootstrap/tasks/prechecks.yml* file, there are the checks for *CPUS & RAM* diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md index 3ee54086..99c80352 100644 --- a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md +++ b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md @@ -39,46 +39,46 @@ tasks such as 2. [Controllers](https://github.com/nephio-project/free5gc/tree/main/controllers) * **Reconciler**: The XXFDeploymentReconciler struct is responsible for reconciling the state of the XXFDeployment - resource in the Kubernetes cluster. It implements the *Reconcile* function, which is called by the Controller Runtime - framework when changes occur to the XXFDeployment resource. The *Reconcile* function performs various operations such - as creating or updating the **ConfigMap** and **Service** resources associated with the XXFDeployment. + resource in the Kubernetes cluster. It implements the Reconcile function, which is called by the Controller Runtime + framework when changes occur to the XXFDeployment resource. The Reconcile function performs various operations such + as creating or updating the ConfigMap and Service resources associated with the XXFDeployment. Overall, the XXFDeploymentReconciler struct acts as the controller for the XXFDeployment resource, ensuring that the cluster state aligns with the desired state specified by the user. * **Resources**: functions that provide the necessary logic to create the required Kubernetes resources for an XXF deployment, including the deployment, service, and configuration map: - * *createDeployment*: This function creates a Deployment resource for the AMF deployment. It defines the desired + * createDeployment: This function creates a Deployment resource for the AMF deployment. It defines the desired state of the deployment, including the number of replicas, container image, ports, command, arguments, volume mounts, resource requirements, and security context. - * *createService*: This function creates a Service resource for the AMF deployment. It defines the desired state of + * createService: This function creates a Service resource for the AMF deployment. It defines the desired state of the service, including the selector for the associated deployment and the ports it exposes. - * *createConfigMap*: This function creates a ConfigMap resource for the AMF deployment. It generates the + * createConfigMap: This function creates a ConfigMap resource for the AMF deployment. It generates the configuration data for the AMF based on the provided template values and renders it into the amfcfg.yaml file. - * *createResourceRequirements*: This function calculates the resource requirements (CPU and memory limits and + * createResourceRequirements: This function calculates the resource requirements (CPU and memory limits and requests) for the AMF deployment based on the specified capacity and sets them in a ResourceRequirements object. - * *createNetworkAttachmentDefinitionNetworks*: This function creates the network attachment definition networks for + * createNetworkAttachmentDefinitionNetworks: This function creates the network attachment definition networks for the AMF deployment. It uses the CreateNetworkAttachmentDefinitionNetworks function from the controllers package to generate the network attachment definition YAML based on the provided template name and interface configurations. * **Templates**: The configuration template includes various parameters. Example for AMF: version, description, ngapIpList, sbi, nrfUri, amfName, serviceNameList, servedGuamiList, supportTaiList, plmnSupportList, supportDnnList, security settings, networkName, locality, networkFeatureSupport5GS, timers, and logger configurations. - The *renderConfigurationTemplate* function takes a struct (configurationTemplateValues) containing the values for + The renderConfigurationTemplate function takes a struct (configurationTemplateValues) containing the values for placeholders in the template and renders the final configuration as a string. The rendered configuration can then be used by the AMF application. * **Status**: It holds the logic to get the status of the deployment and displaying it as "Available," "Progressing," - and "ReplicaFailure".The function returns the *NFDeploymentStatus* object and a boolean value indicating whether the + and "ReplicaFailure".The function returns the NFDeploymentStatus object and a boolean value indicating whether the status has been updated or not. 3. [Config](https://github.com/nephio-project/free5gc/tree/main/config) - There are [Kustomization](https://github.com/kubernetes-sigs/kustomize) file for a Kubernetes application, specifying various configuration options and resources for the application. + There are [Kustomization](https://github.com/kubernetes-sigs/kustomize) files for a Kubernetes application, specifying various configuration options and resources for the application. In the */default* folder there are: * *Namespace*: Defines the namespace (free5gc) where all resources will be deployed. * *Name Prefix*: Specifies a prefix (free5gc-operator-) that will be prepended to the names of all resources. * *Common Labels*: Allows adding labels to all resources and selectors. Currently commented out. -* *Bases*: Specifies the directories (../crd, ../rbac, ../operator) containing the base resources for the application. +* *Bases*: Specifies the directories (*../crd*, *../rbac*, *../operator*) containing the base resources for the application. In the *crd/base* folder there are CRDs for the workload network functions. They define the schema for the "XXFDeployment" resource under the "workload.nephio.org" group. Also, there are YAML config files for teaching kustomize how to substitute *name* and *namespace* reference in CRD. diff --git a/content/en/docs/guides/install-guides/explore-sandbox.md b/content/en/docs/guides/install-guides/explore-sandbox.md index 2bd89bdf..742260ef 100644 --- a/content/en/docs/guides/install-guides/explore-sandbox.md +++ b/content/en/docs/guides/install-guides/explore-sandbox.md @@ -18,28 +18,28 @@ Ansible install scripts. | Component | Purpose | | --------- | ---------------------------------------------------------------------------------------- | -| docker | Used to host Kubernetes clusters created by KinD | -| kind | Used to create clusters in docker | -| kubectl | Used to control clusters created by KinD | -| kpt | Used to install packages (software and metadata) on k8s clusters | -| cni | Used to implement the k8s network model for the KinD clusters | -| gtp5g | A Linux module that supports the 3GPP GPRS tunneling protocol (required by free5gc NFs) | +| *docker* | Used to host Kubernetes clusters created by KinD | +| *kind* | Used to create clusters in docker | +| *kubectl* | Used to control clusters created by KinD | +| *kpt* | Used to install packages (software and metadata) on k8s clusters | +| *cni* | Used to implement the k8s network model for the KinD clusters | +| *gtp5g* | A Linux module that supports the 3GPP GPRS tunneling protocol (required by free5gc NFs) | The Ansible install scripts use kind to create the Management cluster. Once the Management KinD cluster is created, the -install uses kpt packages to install the remainder of the software. +install uses *kpt* packages to install the remainder of the software. ## Components Installed on the Management KinD cluster -Everything is installed on the Management KinD cluster by Ansible scripts using kpt packages. +Everything is installed on the Management KinD cluster by Ansible scripts using *kpt* packages. -The install unpacks each kpt package in the */tmp* directory. It then applies the kpt functions to the packages and -applies the packages to the Management KinD cluster. This allows the user to check the status of the kpt packages in +The install unpacks each *kpt* package in the */tmp* directory. It then applies the *kpt* functions to the packages and +applies the packages to the Management KinD cluster. This allows the user to check the status of the *kpt* packages in the cluster using the `kpt live status` command on the unpacked packages in the */tmp* directory. -The rendered kpt packages containing components are unpacked in the */tmp/kpt-pkg* directory. The rendered kpt packages -that create the *mgmt* and *mgmt-staging* repositories are unpacked in the */tmp/repository* directory. The rendered kpt -package containing the rootsync configuration for the *mgmt* repository is unpacked in the */tmp/rootsync* directory. -You can examine the contents of any rendered kpt packager by examining the contents of these directories. +The rendered *kpt* packages containing components are unpacked in the */tmp/kpt-pkg* directory. The rendered *kpt* packages +that create the *mgmt* and *mgmt-staging* repositories are unpacked in the */tmp/repository* directory. The rendered *kpt* +package containing the *rootsync* configuration for the *mgmt* repository is unpacked in the */tmp/rootsync* directory. +You can examine the contents of any rendered *kpt* packager by examining the contents of these directories. ```bash /tmp/kpt-pkg/ /tmp/repository /tmp/rootsync/ @@ -58,7 +58,7 @@ You can examine the contents of any rendered kpt packager by examining the conte └── resource-backend ``` -You can check the status of an applied kpt package using a `kpt live status package_dir` command. +You can check the status of an applied *kpt* package using a `kpt live status package_dir` command. ```bash kpt live status /tmp/kpt-pkg/nephio-controllers/ @@ -129,13 +129,13 @@ interacts closely with. ## Some Useful Commands -Easily get the kubeconfig for a CAPI KinD cluster: +Easily get the *kubeconfig* for a CAPI KinD cluster: ```bash get_capi_kubeconfig regional ``` -will create a file `regional-kubeconfig` used to connect to that +will create a file *regional-kubeconfig* used to connect to that cluster. You can query docker to see the docker images running KinD diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 3df9a50b..b9bc0dcd 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -19,11 +19,11 @@ Regardless of the specific choices you make, you will need the following prerequisites. This is in addition to any prerequisites that are specific to your environment and choices. - a Linux workstation with internet access - - `kubectl` [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation - - `kpt` [installed](https://kpt.dev/installation/kpt-cli) on your workstation + - *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation + - *kpt* [installed](https://kpt.dev/installation/kpt-cli) on your workstation (version v1.0.0-beta.43 or later) - - `porchctl` [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation - - Sudo-less `docker`, `podman`, or `nerdctl`. If using `podman` or `nerdctl`, + - *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation + - Sudo-less *docker*, *podman*, or *nerdctl*. If using *podman* or *nerdctl*, you must set the [`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) environment variable. @@ -31,12 +31,12 @@ environment variable. As part of all installations, you will create or utilize an existing Kubernetes management cluster. The management cluster must have internet access, and must be a non-EOL Kubernetes version. Additionally: - - Your default `kubectl` context should point to the cluster + - Your default *kubectl* context should point to the cluster - You will need cluster administrator privileges (in particular you will need to be able to create namespaces and other cluster-scoped resources). -You will use `kpt` for most of the installation packages in these instructions, -though you could also use `kubectl` directly to apply the resources, once they +You will use *kpt* for most of the installation packages in these instructions, +though you could also use *kubectl* directly to apply the resources, once they are configured. After installing the prerequisites, create a local directory on your @@ -49,7 +49,7 @@ cd nephio-install ``` The instructions for setting up the opinionated installations will assume you -have installed the prerequisites and created the `nephio-install` directory. +have installed the prerequisites and created the *nephio-install* directory. ## Opinionated Installations @@ -118,12 +118,12 @@ Ingress or Gateway is recommended. ### Nephio WebUI Authentication and Authorization -In the default configuration, the Nephio WebUI *is wide open with no -authentication*. The webui itself authenticates to the cluster using a static +In the default configuration, the Nephio WebUI **is wide open with no +authentication**. The webui itself authenticates to the cluster using a static service account, which is bound to the cluster admin role. Any user accessing -the webui is *acting as a cluster admin*. +the webui is **acting as a cluster admin**. -This configuration is designed for *testing and development only*. You must not +This configuration is designed for **testing and development only**. You must not use this configuration in any other situation, and even for testing and development it must not be exposed on the internet (for example, via a LoadBalancer service, Ingress, or Route). diff --git a/content/en/docs/guides/install-guides/install-on-gce.md b/content/en/docs/guides/install-guides/install-on-gce.md index 2bcc5066..e3ed8a85 100644 --- a/content/en/docs/guides/install-guides/install-on-gce.md +++ b/content/en/docs/guides/install-guides/install-on-gce.md @@ -15,7 +15,7 @@ to simulate a topology with a Nephio management cluster and three workload clust ### GCE Prerequisites -You will need an account in GCP and `gcloud` installed on your local environment. +You will need an account in GCP and *gcloud* installed on your local environment. ### Create a Virtual Machine on GCE @@ -64,7 +64,7 @@ browse the Nephio Web UI ## Open Terminal -You will probably want a second ssh window open to run `kubectl` commands, etc., +You will probably want a second ssh window open to run *kubectl* commands, etc., without the port forwarding (which would fail if you try to open a second ssh connection with that setting). diff --git a/content/en/docs/guides/install-guides/install-on-gcp.md b/content/en/docs/guides/install-guides/install-on-gcp.md index 49790f85..8ffe41e8 100644 --- a/content/en/docs/guides/install-guides/install-on-gcp.md +++ b/content/en/docs/guides/install-guides/install-on-gcp.md @@ -31,27 +31,27 @@ In addition to the general prerequisites, you will need: - A GCP account. This account should have enough privileges to create projects, enable APIs in those projects, and create the necessary resources. -- [Google Cloud CLI](https://cloud.google.com/sdk/docs) (`gcloud`) installed and set up on your workstation. +- [Google Cloud CLI](https://cloud.google.com/sdk/docs) (*gcloud*) installed and set up on your workstation. - git installed on your workstation. ## Setup Your Environment -To make the instructions (and possibly your life) simpler, you can create a `gcloud` configuration and a project for +To make the instructions (and possibly your life) simpler, you can create a *gcloud* configuration and a project for Nephio. In the commands below, several environment variables are used. You can set them to appropriate values for you. Set -`LOCATION` to a region to create a regional Nephio management cluster, or to a zone to create a zonal cluster. Regional +*LOCATION* to a region to create a regional Nephio management cluster, or to a zone to create a zonal cluster. Regional clusters have increased availability but higher resource demands. -- `PROJECT` is an existing project ID, or the ID to use for a new project. -- `ACCOUNT` should be your Google account mentioned in the prerequisites. -- `REGION` is the region for your Config Controller. See [this link] for the list of supported regions. -- `LOCATION` is the location (region or zone) for your Nephio management cluster as well as any workload clusters you +- *PROJECT* is an existing project ID, or the ID to use for a new project. +- *ACCOUNT* should be your Google account mentioned in the prerequisites. +- *REGION* is the region for your Config Controller. See [this link] for the list of supported regions. +- *LOCATION* is the location (region or zone) for your Nephio management cluster as well as any workload clusters you create. Setting this will not limit you to this location, but it will be what is used in this guide. Note that Config Controller is always regional. -- `WEBUIFQDN` is the fully qualified domain name you would like to use for the web UI. -- `MANAGED_ZONE` is the GCP name for the zone where you will put the DNS entry for `WEBUIFQDN`. Note that it is not the - domain name, but rather the managed zone name used in GCP - for example, `my-zone-name`, not `myzone.example.com`. +- *WEBUIFQDN* is the fully qualified domain name you would like to use for the web UI. +- *MANAGED_ZONE* is the GCP name for the zone where you will put the DNS entry for *WEBUIFQDN*. Note that it is not the + domain name, but rather the managed zone name used in GCP - for example, *my-zone-name*, not *myzone.example.com*. Set the environment variables: @@ -64,7 +64,7 @@ WEBUIFQDN=nephio.example.com MANAGED_ZONE=your-managed-zone-name ``` -First, create the configuration. You can view and switch between `gcloud` configurations with +First, create the configuration. You can view and switch between *gcloud* configurations with `gcloud config configurations list` and `gcloud config configurations activate`. ```bash @@ -116,7 +116,7 @@ method for selecting and assigning billing accounts. See the [project billing account documentation](https://cloud.google.com/billing/docs/how-to/modify-project#how-to-change-ba), or consult with the GCP administrators in your organization. -Next, set the new project as the default in your `gcloud` configuration: +Next, set the new project as the default in your *gcloud* configuration: ```bash gcloud config set project $PROJECT @@ -262,7 +262,7 @@ gcloud projects add-iam-policy-binding ${PROJECT} \ The Porch SA will also be used for synchronizing GKE Fleet information to the Nephio cluster, for use in our deployments. For this, it needs the -`roles/gkehub.viewer` role: +*roles/gkehub.viewer* role: ```bash gcloud projects add-iam-policy-binding ${PROJECT} \ @@ -380,7 +380,7 @@ If not, you should retrieve the credentials with: gcloud anthos config controller get-credentials nephio-cc --location $REGION ``` -There is one more step - granting privileges to the CC cluster to manage GCP resources in this project. With `kubectl` +There is one more step - granting privileges to the CC cluster to manage GCP resources in this project. With *kubectl* pointing at the CC cluster, retrieve the service account email address used by CC: ```bash @@ -398,7 +398,7 @@ service-NNNNNNNNNNNN@gcp-sa-yakima.iam.gserviceaccount.com -Grant that service account `roles/editor`, which allows full management access to the project, except for IAM and a few +Grant that service account *roles/editor*, which allows full management access to the project, except for IAM and a few other things: ```bash @@ -453,8 +453,8 @@ version: 1 -The service account also needs to create Cloud Source Repositories which is not par of the `roles/editor`, role. So, add -the `roles/source.admin` role as well: +The service account also needs to create Cloud Source Repositories which is not par of the *roles/editor*, role. So, add +the *roles/source.admin* role as well: ```bash gcloud projects add-iam-policy-binding $PROJECT \ @@ -465,7 +465,7 @@ gcloud projects add-iam-policy-binding $PROJECT \ Granting IAM privileges is not necessary for this setup, but if you did want to use separate service accounts per -workload cluster, you would need to grant those privileges as well (`roles/owner` for example). +workload cluster, you would need to grant those privileges as well (*roles/owner* for example). ## Setting Up GitOps for Config Controller @@ -536,7 +536,7 @@ Customized package for deployment. -You need to add your project ID to your clone of the package. You can manually edit the `gcp-context.yaml` or run the +You need to add your project ID to your clone of the package. You can manually edit the *gcp-context.yaml* or run the following command: ```bash @@ -602,14 +602,14 @@ Config Sync will now synchronize that repository to your Config Controller. ## Provisioning Your Management Cluster -You will use CC to provision the Nephio management cluster and associated resources, by way of the `config-control` +You will use CC to provision the Nephio management cluster and associated resources, by way of the *config-control* repository. The [cc-cluster-gke-std-csr-cs](https://github.com/nephio-project/catalog/tree/main/infra/gcp/cc-cluster-gke-std-csr-cs) package uses CC to create a cluster and a cloud source repository, add the cluster to a fleet, and install and configure -Config Sync on the cluster to point to the new repository. This is similar to what the `nephio-workload-cluster` +Config Sync on the cluster to point to the new repository. This is similar to what the *nephio-workload-cluster* package does in the Sandbox exercises, except that it uses GCP services to create the repository and bootstrap Config Sync, rather than Nephio controllers. -First, pull the cluster package into your clone of the `config-control` +First, pull the cluster package into your clone of the *config-control* repository: ```bash @@ -626,7 +626,7 @@ git commit -m "Initial clone of GKE package" ``` Next, configure the package for your environment. Specifically, you need to add your project ID and location to your -clone of the package. You can manually edit the `gcp-context.yaml` or run the following commands: +clone of the package. You can manually edit the *gcp-context.yaml* or run the following commands: ```bash kpt fn eval nephio --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-name gcp-context -- 'by-path=data.project-id' "put-value=${PROJECT}" @@ -674,7 +674,7 @@ To check the status, use the console: ![Console Packages](/static/images/install-guides/gcp-console-packages.png) -Alternatively, you can use `kubectl` to view the status of the `root-sync`: +Alternatively, you can use `kubectl` to view the status of the *root-sync*: ```bash kubectl describe rootsync -n config-management-system root-sync @@ -771,8 +771,8 @@ nephio us-central1 1.27.3-gke.100 34.xxx.xx.xx e2-medium 1 -Once the management cluster is `RUNNING`, retrieve the credentials and -store them as a `kubectl` context: +Once the management cluster is RUNNING, retrieve the credentials and +store them as a *kubectl* context: ```bash gcloud container clusters get-credentials --location $LOCATION nephio @@ -800,7 +800,7 @@ If the context is not current, use this command to make it current: kubectl config use-context "gke_${PROJECT}_${LOCATION}_nephio" ``` -As a final step, return to the `nephio-install` directory as your current +As a final step, return to the *nephio-install* directory as your current working directory: ```bash @@ -827,8 +827,8 @@ nephio your-nephio-project-id https://source.developers.google.com/p/ -Ensure your current working directory is `nephio-install`, and then clone the -`nephio` repository locally: +Ensure your current working directory is *nephio-install*, and then clone the +*nephio* repository locally: ```bash gcloud source repos clone nephio @@ -845,7 +845,7 @@ Project [your-nephio-project-id] repository [nephio] was cloned to [/home/your-u -Navigate to that directory, and pull out the `nephio-mgmt` package, which +Navigate to that directory, and pull out the *nephio-mgmt* package, which contains all the necessary Nephio components as subpackages: - Porch - Nephio Controllers @@ -1027,7 +1027,7 @@ set up OAuth. In particular you need to [create the client ID](/content/en/docs/ and the [secret](/content/en/docs/guides/install-guides/webui-auth-gcp.md#create-the-secret-in-the-cluster) manually. -The `nephio-webui` subpackage in `nephio-mgmt` is already set up for +The *nephio-webui* subpackage in *nephio-mgmt* is already set up for Google OAuth 2.0; you can follow the instructions in the linked document if you prefer OIDC. @@ -1146,12 +1146,12 @@ To https://source.developers.google.com/p/your-nephio-project-id/nephio ## Accessing Nephio -Accessing Nephio with `kubectl` or `kpt` can be done from your workstation, so long as you use the context for the +Accessing Nephio with *kubectl* or *kpt* can be done from your workstation, so long as you use the context for the Nephio management cluster. To access the WebUI, you need to create a DNS entry pointing to the load balancer IP serving the Ingress resources. The Ingress included in the Web UI package will use Cert Manager to automatically generate a self-signed certificate for the -`WEBUIFQDN` value. +*WEBUIFQDN* value. Find the IP address using this command: @@ -1169,7 +1169,7 @@ The output is similar to: -You will need to add this as an `A` record for the name you used in `WEBUIFQDN`. If you are using Google Cloud DNS for +You will need to add this as an **A** record for the name you used in *WEBUIFQDN*. If you are using Google Cloud DNS for that zone, first find the managed zone name: ```bash @@ -1188,8 +1188,8 @@ your-managed-zone-name example.com. -In this case, you would use `your-managed-zone-name`, which is the name for the -`example.com.` zone. +In this case, you would use *your-managed-zone-name*, which is the name for the +*example.com.* zone. Start a transaction to add a record set: @@ -1206,7 +1206,7 @@ Transaction started [transaction.yaml]. -Add the specific IP address as an A record, with the fully-qualified domain name +Add the specific IP address as an **A** record, with the fully-qualified domain name of the site: ```bash diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index b43f7b6d..99c654fc 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -10,15 +10,15 @@ weight: 7 * 4 vCPU * 8 GB RAM * Kubernetes version 1.26+ - * `kubectl` [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) + * *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) * **Ingress/Load Balancer**: [MetalLB](https://metallb.universe.tf/), but only internally to the VM * Cluster Edge * 2 vCPU 1 NODE * 4 GB RAM * Kubernetes version 1.26+ - * `kubectl` [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) -* `kpt` [installed](https://kpt.dev/installation/kpt-cli) (version v1.0.0-beta.43 or later) -* `porchctl` [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation + * *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) +* *kpt* [installed](https://kpt.dev/installation/kpt-cli) (version v1.0.0-beta.43 or later) +* *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation ## Installation of the management cluster @@ -29,13 +29,13 @@ weight: 7 ## Manual Installation of the Edge cluster using kpt -All the workload clusters need config-sync, root-sync +All the workload clusters need *config-sync*, *root-sync* and a cluster git repository to manage packages. The below steps have to be repeated for each workload cluster: ### Install Config-sync -Install config-sync using: +Install *config-sync* using: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@@origin/v3.0.0 @@ -53,7 +53,7 @@ If you want to use GitHub or GitLab then follow below steps Get a [GitHub token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) if your repository is private, to allow Porch to make modifications. -Register the edge repository using kpt cli or nephio web-ui. +Register the edge repository using *kpt* cli or Nephio WebUI. ```bash GITHUB_USERNAME= @@ -80,22 +80,22 @@ kpt live apply --reconcile-timeout=15m --output=table {{% alert title="Note" color="primary" %}} -* For management cluster you have to name the repository as `mgmt`. -* In the `repository` package by default gitea address is `172.18.0.200:3000` in `repository/set-values.yaml` +* For management cluster you have to name the repository as *mgmt*. +* In the *repository* package by default gitea address is *172.18.0.200:3000* in *repository/set-values.yaml* change this to your git address. -* `repository/token-configsync.yaml` and `repository/token-porch.yaml` are responsible for creating secrets with the help of Nephio token controller for accessing git instance for root-sync. You would need the name of config-sync token to provide it to root-sync. +* *repository/token-configsync.yaml* and *repository/token-porch.yaml* are responsible for creating secrets with the help of Nephio token controller for accessing git instance for root-sync. You would need the name of config-sync token to provide it to root-sync. {{% /alert %}} ### Install Root-sync -Get the Root-sync kpt package and edit it: +Get the *root-sync* *kpt* package and edit it: ```bash kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@@origin/v3.0.0 ``` -Change `./rootsync/rootsync.yaml` and point `spec.git.repo` to the edge git repository and the +Change *./rootsync/rootsync.yaml* and point *spec.git.repo* to the edge git repository and the ```yaml spec: @@ -108,7 +108,7 @@ Change `./rootsync/rootsync.yaml` and point `spec.git.repo` to the edge git repo If need credentials to access repository your repository then copy the token name from previous section and provide it in -`./rootsync/rootsync.yaml` +*./rootsync/rootsync.yaml*. ```yaml spec: @@ -130,7 +130,7 @@ kpt live apply rootsync --reconcile-timeout=15m --output=table If the output of `kubectl get rootsyncs.configsync.gke.io -A` -is similar as below then root-sync is properly configured. +is similar as below then *root-sync* is properly configured. ```console kubectl get rootsyncs.configsync.gke.io -A @@ -150,4 +150,4 @@ kpt live apply workload-crds --reconcile-timeout=15m --output=table ## Deploy packages to the edge clusters -Using web-ui or command line add a new deployment to the edge workload cluster. +Using WebUI or command line add a new deployment to the edge workload cluster. diff --git a/content/en/docs/guides/install-guides/install-on-openshift.md b/content/en/docs/guides/install-guides/install-on-openshift.md index 861b9f78..d199a2fb 100644 --- a/content/en/docs/guides/install-guides/install-on-openshift.md +++ b/content/en/docs/guides/install-guides/install-on-openshift.md @@ -25,7 +25,7 @@ In this guide, you will set up Nephio with: ## Prerequisites - A Red Hat Account and access to https://console.redhat.com/openshift/ -- OpenShift cli client `oc`. [Download here](https://console.redhat.com/openshift/downloads) +- OpenShift cli client *oc*. [Download here](https://console.redhat.com/openshift/downloads) ## Setup the Management Cluster @@ -99,8 +99,8 @@ and the [common components](/content/en/docs/guides/install-guides/common-compon ``` - Login - - user: gitea - - password: password + - user: *gitea* + - password: *password* ## Install edge clusters diff --git a/content/en/docs/guides/install-guides/install-on-single-vm.md b/content/en/docs/guides/install-guides/install-on-single-vm.md index 6d896153..6c907104 100644 --- a/content/en/docs/guides/install-guides/install-on-single-vm.md +++ b/content/en/docs/guides/install-guides/install-on-single-vm.md @@ -28,12 +28,12 @@ In addition to the general prerequisites, you will need: * Access to a Virtual Machine provided by an hypervisor ([VirtualBox](https://www.virtualbox.org/), [Libvirt](https://libvirt.org/)) and running an OS supported by Nephio (Ubuntu 20.04/22.04, Fedora 34) with a minimum of 16 vCPUs and 32 GB in RAM. -* [Kubernetes IN Docker](https://kind.sigs.k8s.io/) (`kind`) installed and set up your workstation. +* [Kubernetes IN Docker](https://kind.sigs.k8s.io/) (*kind*) installed and set up your workstation. ## Provisioning Your Management Cluster The Cluster API services require communication with the Docker socket for creation of workload clusters. The command -below creates an All-in-One Nephio management cluster through the KinD tool, mapping the `/var/run/docker.sock` socket +below creates an All-in-One Nephio management cluster through the KinD tool, mapping the */var/run/docker.sock* socket file for Cluster API communication. ```bash @@ -52,7 +52,7 @@ EOF ## Gitea Installation While you may use other Git providers as well, Gitea is required in the R2 setup. To install Gitea, use `kpt`. From your -`nephio-install` directory, run: +*nephio-install* directory, run: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@@origin/v3.0.0 @@ -85,7 +85,7 @@ kpt live init cert-manager kpt live apply cert-manager --reconcile-timeout 15m --output=table ``` -Once `cert-manager` is installed, you can proceed with the installation of Cluster API components +Once *cert-manager* is installed, you can proceed with the installation of Cluster API components ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi@@origin/v3.0.0 @@ -116,11 +116,11 @@ kpt live apply cluster-capi-kind-docker-templates --reconcile-timeout 15m --outp ## Installing Packages -The management or workload cluster both need config-sync, root-sync and a cluster git repository to manage packages. +The management or workload cluster both need *config-sync*, *root-sync* and a cluster git repository to manage packages. ### Install Config-sync -Install config-sync using: +Install *config-sync* using: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@@origin/v3.0.0 @@ -142,10 +142,10 @@ kpt live apply --reconcile-timeout=15m --output=table {{% alert title="Note" color="primary" %}} -* For management cluster you have to name the repository as `mgmt`. -* In the `repository` package the default Gitea address is `172.18.0.200:3000`. -In `repository/set-values.yaml` change this to your Gitea address. -* `repository/token-configsync.yaml` and `repository/token-porch.yaml` are +* For management cluster you have to name the repository as *mgmt*. +* In the *repository* package the default Gitea address is *172.18.0.200:3000*. +In *repository/set-values.yaml* change this to your Gitea address. +* *repository/token-configsync.yaml* and *repository/token-porch.yaml* are responsible for creating secrets with the help of the Nephio token controller for accessing the git instance for root-sync. You would need the name of the config-sync token to provide it to root-sync. @@ -154,13 +154,13 @@ You would need the name of the config-sync token to provide it to root-sync. ### Install Root-sync -Get the Root-sync kpt package and edit it: +Get the *root-sync* kpt package and edit it: ```bash kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@@origin/v3.0.0 ``` -Change `./rootsync/rootsync.yaml` and point `spec.git.repo` to the edge git repository: +Change *./rootsync/rootsync.yaml* and point *spec.git.repo* to the edge git repository: ```yaml spec: @@ -175,7 +175,7 @@ Change `./rootsync/rootsync.yaml` and point `spec.git.repo` to the edge git repo If you need credentials to access your repository then copy the token name from the previous section and provide it in -`./rootsync/rootsync.yaml`: +*./rootsync/rootsync.yaml*: ```yaml spec: diff --git a/content/en/docs/guides/install-guides/package-transformations.md b/content/en/docs/guides/install-guides/package-transformations.md index 8819cc45..61b6b19f 100644 --- a/content/en/docs/guides/install-guides/package-transformations.md +++ b/content/en/docs/guides/install-guides/package-transformations.md @@ -13,24 +13,24 @@ Before reading this, please read [the kpt book](https://kpt.dev/book/). The `kpt pkg get --for-deployment https:///@/ -` command downloads a kpt package from a repository. +` command downloads a *kpt* package from a repository. The fields in the command above are as follows: | Field | Description | | ---------------- | -------------------------------------------------------------------------------- | -| `repo-path` | The path in the repository to the kpt package | -| `repo-pkg-name` | The name of the kpt package in the repository | -| `pkg-version` | The version of the kpt package | -| `local-pkg-name` | The local name of the kpt package in the repository, defaults to `repo-pkg-name` | +| repo-path | The path in the repository to the *kpt* package | +| repo-pkg-name | The name of the *kpt* package in the repository | +| pkg-version | The version of the *kpt* package | +| local-pkg-name | The local name of the *kpt* package in the repository, defaults to `repo-pkg-name` | `kpt pkg get` make the following transformations: -1. The `metadata.name` field in the root `Kptfile` in the package is changed - from whatever value it has to `local-pkg-name` -2. The `metadata.namespace` field in the root `Kptfile` in the package is +1. The metadata.name field in the root *Kptfile* in the package is changed + from whatever value it has to local-pkg-name +2. The metadata.namespace field in the root *Kptfile* in the package is removed -3. `upstream` and `upstreamlock` root fields are added to the root `Kptfile` as +3. upstream and upstreamlock root fields are added to the root *Kptfile* as follows: ```yaml @@ -49,9 +49,9 @@ upstreamLock: ref: commit: 0123456789abcdef0123456789abcdef01234567 ``` -4. The `data.name` field in the root `package-context.yaml` files is changed to - be `local-pkg-name` -5. The `package-context.yaml` file is added if it does not exist with the +4. The data.name field in the root *package-context.yaml* files is changed to + be local-pkg-name +5. The *package-context.yaml* file is added if it does not exist with the following content: ```yaml @@ -65,15 +65,15 @@ data: name: ``` -6. The `data.name` field in `package-context.yaml` files in the sub kpt packages is +6. The data.name field in *package-context.yaml* files in the sub *kpt* packages is changed to be the name of the sub package -7. All other sub-fields under the `data:` field are deleted -8. The comment `metadata: # kpt-merge: /` is added to root - `metadata` fields on all YAML documents in the kpt package and enclosed - sub-packages that have a root `apiVersion` and `kind` field if such a comment - does not already exist. The `namespace` and `name` values used are the values - of those fields in the `metadata` field. Note that a YAML file can contain - multiple YAML documents and each root `metadata` field is commented. For +7. All other sub-fields under the data: field are deleted +8. The comment metadata: *# kpt-merge: \/\* is added to root + metadata fields on all YAML documents in the *kpt* package and enclosed + sub-packages that have a root apiVersion and kind field if such a comment + does not already exist. The namespace and name values used are the values + of those fields in the metadata field. Note that a YAML file can contain + multiple YAML documents and each root metadata field is commented. For example: ```yaml @@ -82,13 +82,13 @@ metadata: # kpt-merge: cert-manager/cert-manager-cainjector namespace: cert-manager ``` -9. The annotation `internal.kpt.dev/upstream-identifier: - '|||'` is added to root - `metadata.annotations:` fields on all YAML documents in the kpt package and - enclosed sub-packages that have a root `apiVersion:` and `kind:` field if - such an annotation does not already exist. The `namespace` and `name` values - used are the values of those fields in the `metadata` field. Note that a YAML - file can contain multiple YAML documents and each root `metadata` field is +9. The annotation internal.kpt.dev/upstream-identifier: + *\|\|\|\* is added to root + metadata.annotations: fields on all YAML documents in the *kpt* package and + enclosed sub-packages that have a root apiVersion: and kind: field if + such an annotation does not already exist. The namespace and name values + used are the values of those fields in the metadata field. Note that a YAML + file can contain multiple YAML documents and each root metadata field is commented. For example: ```yaml @@ -107,15 +107,15 @@ metadata: # kpt-merge: capi-kubeadm/leader-election-rolebinding The `kpt fn render ` runs kpt functions on a local package, thus applying local changes to the package. -In the Nephio sandbox installation, kpt fn render only acts on the `repository` and -`rootsync` kpt packages from +In the Nephio sandbox installation, kpt fn render only acts on the repository and +*rootsync* *kpt* packages from [nephio-example-packages](https://github.com/nephio-project/nephio-example-packages). #### repository package -The `repository` package has a kpt function written in +The repository package has a kpt function written in [starlark](https://github.com/bazelbuild/starlark), which is invoked by a -pipeline specified in the `kptfile`. +pipeline specified in the *kptfile*. ```yaml pipeline: @@ -124,48 +124,48 @@ pipeline: configPath: set-values.yaml ``` -The starlark function is specified in the `set-values.yaml` file. It makes the +The starlark function is specified in the *set-values.yaml* file. It makes the following transformations on the repositories: -1. In the file `repo-gitea.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.description` field gets the value of ` repository` -2. In the file `repo-porch.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.git.repo` field gets the value of - `"http://172.18.0.200:3000/nephio/.git` - - the `spec.git.secretRef.name` field gets the value of - `-access-token-porch` - - if the `` is called `mgmt-staging`, then the following extra +1. In the file *repo-gitea.yaml* + - the metadata.name field gets the value of \ + - the spec.description field gets the value of \ repository +2. In the file *repo-porch.yaml* + - the metadata.name field gets the value of \ + - the spec.git.repo field gets the value of + "http://172.18.0.200:3000/nephio/\.git + - the spec.git.secretRef.name field gets the value of + \-access-token-porch + - if the \ is called mgmt-staging, then the following extra changes are made: - - the `spec.deployment` field is set to `false` (it defaults to `true`) - - the annotation `metadata.annotations.nephio.org/staging: "true"` is added -3. In the file `token-configsync.yaml` - - the `metadata.name` field gets the value of - `-access-token-configsync` - - the `metadata.namespace` field gets the value of `config-management-system` -4. In the file `token-porch.yaml` - - the `metadata.name` field gets the value of - `-access-token-porch` + - the spec.deployment field is set to false (it defaults to true) + - the annotation metadata.annotations.nephio.org/staging: "true" is added +3. In the file *token-configsync.yaml* + - the metadata.name field gets the value of + \-access-token-configsync + - the metadata.namespace field gets the value of config-management-system +4. In the file *token-porch.yaml* + - the metadata.name field gets the value of + \-access-token-porch #### rootsync Package -The `rootsync` package also has a kpt function written in +The *rootsync* package also has a kpt function written in [starlark](https://github.com/bazelbuild/starlark) specified in the -`set-values.yaml` file. It makes the following transformations on repositories: +*set-values.yaml* file. It makes the following transformations on repositories: -1. In the file `rootsync.yaml` - - the `metadata.name` field gets the value of `` - - the `spec.git.repo` field gets the value of - `"http://172.18.0.200:3000/nephio/.git` +1. In the file *rootsync.yaml* + - the metadata.name field gets the value of \ + - the spec.git.repo field gets the value of + "http://172.18.0.200:3000/nephio/\.git - the `spec.git.secretRef.name` field gets the value of - `-access-token-configsync` + \-access-token-configsync ### kpt live init The `kpt live init ` initializes a local package, making it -ready for application to a cluster. This command creates a `resourcegroup.yaml` -in the kpt package with content similar to: +ready for application to a cluster. This command creates a *resourcegroup.yaml* +in the *kpt* package with content similar to: ```yaml apiVersion: kpt.dev/v1alpha1 @@ -178,9 +178,9 @@ metadata: ``` ## porchctl rpkg for Workload clusters -The `porchctl rpkg` suite of commands that act on `Repository` resources on the -kubernetes cluster in scope. The packages in the `Repository` resources are -*remote packages (rpkg)*. +The `porchctl rpkg` suite of commands that act on Repository resources on the +kubernetes cluster in scope. The packages in the Repository resources are +remote packages (*rpkg*). To see which repositories are in scope: @@ -248,10 +248,10 @@ nephio-example-packages-7895e28d847c0296a204007ed577cd2a4222d1ea nephio-worklo ### Create the Workload cluster package -The Workload cluster package contains `PackageVariant` files for configuring the +The Workload cluster package contains PackageVariant files for configuring the new cluster. -Clone the `nephio-workload-cluster` package into the `mgmt` repository. This +Clone the nephio-workload-cluster package into the *mgmt* repository. This creates the blueprint package for the workload cluster in the management repository. @@ -261,23 +261,23 @@ porchctl rpkg clone -n default nephio-example-packages-7895e28d847c0296a204007ed During the clone operation, the command above performs the following operations: -1. It creates a `drafts/regional/v1` branch on the `mgmt` repository -2. It does the equivalent of a [kpt pkg get](#kpt-pkg-get) on the `nephio-workload-cluster` package into a directory - called `regional` on that branch, with the same transformations on package files carried out as the +1. It creates a drafts/regional/v1 branch on the *mgmt* repository +2. It does the equivalent of a [kpt pkg get](#kpt-pkg-get) on the *nephio-workload-cluster* package into a directory + called *regional* on that branch, with the same transformations on package files carried out as the [kpt pkg get](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit -3. The pipeline specified in the `Kptfile`of the `nephio-workload-cluster` package specifies an `apply-replacements` - specified in the `apply-replacements.yaml` file in the package and uses the value of the - `package-context.yaml:data.name` field set in 2. above (which is the workload cluster name) as follows: +3. The pipeline specified in the *Kptfile* of the *nephio-workload-cluster* package specifies an apply-replacements + specified in the *apply-replacements.yaml* file in the package and uses the value of the + package-context.yaml:data.name field set in 2. above (which is the workload cluster name) as follows: - - In all `PackageVariant` files, the `metadata.name` and `spec.downstream.package` field before the '-' is replaced + - In all *PackageVariant* files, the metadata.name and spec.downstream.package field before the '-' is replaced with that field value. In this way, the downstream package names for all the packages to be pulled from the - `mgmt-staging` repository for the workload cluster are specified. - - In all `PackageVariant` files, the `spec.injectors.WorkloadCluster.name` field is replaced with the workload - cluster name. This gives us the handle for `packageVariant` injection for the workload cluster in question. - - In all `PackageVariant` files, the - `spec.pipeline.mutators.[image=gcr.io/kpt-fn/set-annotations:v0.1.4].configMap.[nephio.org/cluster-name]` + mgmt-staging repository for the workload cluster are specified. + - In all *PackageVariant* files, the spec.injectors.WorkloadCluster.name field is replaced with the workload + cluster name. This gives us the handle for packageVariant injection for the workload cluster in question. + - In all *PackageVariant* files, the + spec.pipeline.mutators.[image=gcr.io/kpt-fn/set-annotations:v0.1.4].configMap.[nephio.org/cluster-name] field is replaced with the workload cluster name. - - In all `WorkloadCluster` files, the `metadata.name` and `spec.clusterName` fields are replaced with the workload + - In all *WorkloadCluster* files, the metadata.name and spec.clusterName fields are replaced with the workload cluster name. We now have a draft blueprint package for our workload cluster ready for further configuration. @@ -306,8 +306,8 @@ porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regi kpt fn eval --image gcr.io/kpt-fn/set-labels:v0.2.0 regional -- "nephio.org/site-type=regional" "nephio.org/region=us-west1" ``` -4. Check that the labels have been set. In all `PackageVariant` and `WorkloadCluster` files, the following - `metadata.labels` fields have been added: +4. Check that the labels have been set. In all *PackageVariant* and *WorkloadCluster* files, the following + metadata.labels fields have been added: ```yaml labels: @@ -332,14 +332,14 @@ porchctl rpkg propose -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 proposed ``` -Proposing the package changes the name of the `drafts/regional/v1` to -`proposed/regional/v1`. There are no changes to the content of the branch. +Proposing the package changes the name of the drafts/regional/v1 to +proposed/regional/v1. There are no changes to the content of the branch. ### Approve the Package and Trigger Configsync Approving the package triggers `configsync`, which triggers creation of the new -workload cluster using all the `PackageVariant` components specified in the -`nephio-workload-cluster` kpt package. +workload cluster using all the *PackageVariant* components specified in the +nephio-workload-cluster *kpt* package. ```bash porchctl rpkg approve -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 @@ -350,19 +350,17 @@ The new cluster comes up after a number of minutes. ## Transformations in the Workload cluster creation -Approving the `regional` Workload cluster package in the `mgmt` repository -triggered configsync to apply the `PackageVariant` configurations in the -`mgmt/regional` package. Let's examine those `PackageVariant` configurations one +Approving the regional Workload cluster package in the *mgmt* repository +triggered configsync to apply the *PackageVariant* configurations in the +*mgmt/regional* package. Let's examine those *PackageVariant* configurations one by one. -In the text below, let's assume we are creating a workload cluster called `lambda`. - ### pv-cluster.yaml: creates the Workload cluster -In the text below, let's assume we are creating a workload cluster called `lambda`. +In the text below, let's assume we are creating a workload cluster called lambda. This package variant transformation results in a package variant of the -`cluster-capi-kind` package called `lambda-package`. The `lambda-package` +*cluster-capi-kind* package called *lambda-package*. The *lambda-package* contains the definition of a pair custom resources that are created when the package is applied. The custom resource pair are instances of the CRDs below @@ -371,42 +369,42 @@ Custom Resource Definition | Controller | Functi clusters.cluster.x-k8s.io | capi-system.capi-controller-manager | Trigger creation and start of the kind cluster | workloadclusters.infra.nephio.org | nephio-system.nephio-controller | Trigger addition of nephio-specific configuration to the kind cluster | -The `PackageVariant` specified in `pv-cluster.yaml` is executed and: +The *PackageVariant* specified in *pv-cluster.yaml* is executed and: 1. Produces a package variant of the [cluster-capi-kind](https://github.com/nephio-project/nephio-example-packages/tree/main/cluster-capi-kind) - package called `lambda-cluster` in the gitea `mgmt` repository on your management + package called lambda-cluster in the gitea *mgmt* repository on your management cluster. -2. Applies the `lambda-cluster` kpt package to create the kind cluster for the +2. Applies the lambda-cluster *kpt* package to create the kind cluster for the workload cluster. #### Package transformations -During creation of the package variant kpt package, the following transformations occur: +During creation of the package variant *kpt* package, the following transformations occur: -1. It creates a `drafts/lambda-cluster/v1` branch on the `mgmt` repository -2. It does the equivalent of a [`kpt pkg get`](#kpt-pkg-get) on the `cluster-capi-kind` package into a directory called - `lambda-cluster` on that branch, with the same transformations on package files carried out as the +1. It creates a drafts/lambda-cluster/v1 branch on the *mgmt* repository +2. It does the equivalent of a [`kpt pkg get`](#kpt-pkg-get) on the *cluster-capi-kind* package into a directory called + lambda-cluster on that branch, with the same transformations on package files carried out as the [`kpt pkg get`](#kpt-pkg-get) command above, this content is checked into the new branch in the initial commit -3. The pipeline specified in the `Kptfile`of the `cluster-capi-kind` package specifies an `apply-replacements` specified - in the `apply-replacements.yaml` file in the package and uses the value of the - `workload-cluster.yaml:spec.clusterName` field set in 2. above (which is the workload cluster name). This has the - value of `example` in the `workload-cluster.yaml` file. This means that in the `cluster.yaml` file the value of field - `metadata.name` is changed from `workload` to `example`. -4. The package variant `spec.injectors` changes specified in the `pv-cluster.yaml` file are applied.
a. The relevant - `pv-cluster.yaml` fields are: ``` spec: injectors: +3. The pipeline specified in the *Kptfile* of the *cluster-capi-kind* package specifies an apply-replacements specified + in the *apply-replacements.yaml* file in the package and uses the value of the + workload-cluster.yaml:spec.clusterName field set in 2. above (which is the workload cluster name). This has the + value of example in the *workload-cluster.yaml* file. This means that in the *cluster.yaml* file the value of field + metadata.name is changed from workload to example. +4. The package variant spec.injectors changes specified in the *pv-cluster.yaml* file are applied.
a. The relevant + *pv-cluster.yaml* fields are: ``` spec: injectors: - kind: WorkloadCluster name: example pipeline: mutators: - image: gcr.io/kpt-fn/set-annotations:v0.1.4 configMap: nephio.org/cluster-name: example ``` - b. The following `PackageVariant` changes are made to the `lambda-cluster` package: + b. The following *PackageVariant* changes are made to the *lambda-cluster* package: - 1. The field `info.readinessGates.conditionType` is added to the `Kptfile` with the value - `config.injection.WorkloadCluster.workload-cluster`. - 2. An extra `pipeline.mutators` entry is inserted in the `Kptfile`. This mutator is the mutator specified in the - `pv-cluster.yaml` package variant specification, which specifies that the annotation - `nephio.org/cluster-name: lambda` should be set on the resources in the package: + 1. The field info.readinessGates.conditionType is added to the *Kptfile* with the value + config.injection.WorkloadCluster.workload-cluster. + 2. An extra pipeline.mutators entry is inserted in the *Kptfile*. This mutator is the mutator specified in the + *pv-cluster.yaml* package variant specification, which specifies that the annotation + nephio.org/cluster-name: lambda should be set on the resources in the package: ```yaml pipeline: @@ -416,8 +414,8 @@ During creation of the package variant kpt package, the following transformation configMap: nephio.org/cluster-name: lambda ``` - 3. The field `status.conditions` is added to the `Kptfile` with the values below. This condition means that the - kpt package is not considered to be applied until the condition `config.injection.WorkloadCluster.workload-cluster` is `True`: + 3. The field status.conditions is added to the *Kptfile* with the values below. This condition means that the + *kpt* package is not considered to be applied until the condition config.injection.WorkloadCluster.workload-cluster is True: ```yaml status: @@ -427,7 +425,7 @@ During creation of the package variant kpt package, the following transformation message: injected resource "lambda" from cluster reason: ConfigInjected ``` - 4. The `spec` in the WorkloadCluster file `workload-cluster.yaml` is set. This is the specification of the extra + 4. The spec in the WorkloadCluster file *workload-cluster.yaml* is set. This is the specification of the extra configuration that will be carried out on the workload cluster once kind has brought it up: ```yaml @@ -438,16 +436,16 @@ During creation of the package variant kpt package, the following transformation - sriov masterInterface: eth1 ``` -5. The amended pipeline specified in the `Kptfile`of the `lambda-cluster` is now re-executed. It was previously executed +5. The amended pipeline specified in the *Kptfile* of the lambda-cluster is now re-executed. It was previously executed in step 3 above but there is now an extra mutator added by the package variant. The following changes result: - a. The new mutator added to the `Kptfile` by the package variant adds the annotation - `nephio.org/cluster-name: lambda` is added to every resource in the package. - b. The existing annotation in the `Kptfile` (coming from the Kptfile in the parent `cluster-capi-kind` package) sets - the value `lambda` of the `spec.clusterName` field in `workload-cluster.yaml` as the value of the `metadata.name` - field in the `cluster.yaml` file. + a. The new mutator added to the *Kptfile* by the package variant adds the annotation + nephio.org/cluster-name: lambda is added to every resource in the package. + b. The existing annotation in the *Kptfile* (coming from the Kptfile in the parent *cluster-capi-kind* package) sets + the value lambda of the spec.clusterName field in *workload-cluster.yaml* as the value of the metadata.name + field in the *cluster.yaml* file. -6. The `lambda-cluster` package is now ready to go. It is proposed and approved and the process of cluster creation +6. The *lambda-cluster* package is now ready to go. It is proposed and approved and the process of cluster creation commences. #### Cluster Creation diff --git a/content/en/docs/guides/install-guides/webui-auth-gcp.md b/content/en/docs/guides/install-guides/webui-auth-gcp.md index 5ef070a5..9321e94f 100644 --- a/content/en/docs/guides/install-guides/webui-auth-gcp.md +++ b/content/en/docs/guides/install-guides/webui-auth-gcp.md @@ -11,7 +11,7 @@ When used with the Web UI running in a GKE cluster, the users authorization role based upon their IAM roles in GCP. If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you -should use `http`, `localhost` and `7007` for the `SCHEME`, `HOSTNAME` and `PORT`; otherwise, use the scheme, DNS name +should use *http*, *localhost* and *7007* for the SCHEME, HOSTNAME and PORT; otherwise, use the scheme, DNS name and port as it will be seen by your browser. You can leave the port off if it is 443 for HTTPS or 80 for HTTP. ## Creating an OAuth 2.0 Client ID @@ -22,17 +22,17 @@ client ID and secret: 1. Sign in to the [Google Console](https://console.cloud.google.com) 2. Select or create a new project from the dropdown menu on the top bar 3. Navigate to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials) -4. Click **Create Credentials** and choose `OAuth client ID` +4. Click **Create Credentials** and choose **OAuth client ID** 5. Configure an OAuth consent screen, if required - - For scopes, select `openid`, `auth/userinfo.email`, `auth/userinfo.profile`, and `auth/cloud-platform`. + - For scopes, select *openid*, *auth/userinfo.email*, *auth/userinfo.profile*, and *auth/cloud-platform*. - Add any users that will want access to the UI if using External user type -6. Set **Application Type** to `Web Application` with these settings: +6. Set **Application Type** to *Web Application* with these settings: - - *Name*: Nephio Web UI (or any other name you wish) - - *Authorized JavaScript origins*: `SCHEME`://`HOSTNAME`:`PORT` - - *Authorized redirect URIs*: `SCHEME`://`HOSTNAME`:`PORT`/api/auth/google/handler/frame + - **Name**: Nephio Web UI (or any other name you wish) + - **Authorized JavaScript origins**: SCHEME://HOSTNAME:PORT + - **Authorized redirect URIs**: SCHEME://HOSTNAME:PORT/api/auth/google/handler/frame 7. Click Create 8. Copy the client ID and client secret displayed @@ -49,16 +49,16 @@ kubectl create secret generic -n nephio-webui nephio-google-oauth-client --from- ## Enable Google OAuth -The webui package has a function that will configure the package for authentication with different services. Edit the -`set-auth.yaml` file to set the `authProvider` field to `google` or run this command: +The *webui* package has a function that will configure the package for authentication with different services. Edit the +*set-auth.yaml* file to set the authProvider field to *google* or run the following command: ```bash kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-name set-auth -- 'by-path=authProvider' 'put-value=google' ``` ## Enable OIDC with Google -The webui package has a function that will configure the package for authentication with different services. Edit the -`set-auth.yaml` file to set the `authProvider` field to `oidc` and the `oidcTokenProvider` to `google`, or run these +The *webui* package has a function that will configure the package for authentication with different services. Edit the +*set-auth.yaml* file to set the authProvider field to *oidc* and the oidcTokenProvider to *google*, or run the following commands: ```bash diff --git a/content/en/docs/guides/install-guides/webui-auth-okta.md b/content/en/docs/guides/install-guides/webui-auth-okta.md index b3d011c5..7d24d74d 100644 --- a/content/en/docs/guides/install-guides/webui-auth-okta.md +++ b/content/en/docs/guides/install-guides/webui-auth-okta.md @@ -6,7 +6,7 @@ weight: 7 --- If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you -should use `localhost` and `7007` for the `HOSTNAME` and `PORT`; otherwise, use the DNS name and port as it will be seen +should use *localhost* and *7007* for the HOSTNAME and PORT; otherwise, use the DNS name and port as it will be seen by your browser. ## Creating an Okta Application @@ -15,21 +15,21 @@ Adapted from the [Backstage](https://backstage.io/docs/auth/okta/provider#create documentation: 1. Log into Okta (generally company.okta.com) -2. Navigate to Menu >> Applications >> Applications >> Create App Integration +2. Navigate to **Menu** >> **Applications** >> **Applications** >> **Create App Integration** 3. Fill out the Create a new app integration form: - - Sign-in method: OIDC - OpenID Connect - - Application type: Web Application - - Click Next + - **Sign-in method**: OIDC - OpenID Connect + - **Application type**: Web Application + - Click **Next** 4. Fill out the New Web App Integration form: - - App integration name: Nephio Web UI (or any other name you wish) - - Grant type: Authorization Code & Refresh Token - - Sign-in redirect URIs: http://HOSTNAME:PORT/api/auth/okta/handler/frame - - Sign-out redirect URIs: http://HOSTNAME:PORT - - Controlled access: (select as appropriate) - - Click Save + - **App integration name**: Nephio Web UI (or any other name you wish) + - **Grant type**: Authorization Code & Refresh Token + - **Sign-in redirect URIs**: http://HOSTNAME:PORT/api/auth/okta/handler/frame + - **Sign-out redirect URIs**: http://HOSTNAME:PORT + - **Controlled access**: (select as appropriate) + - Click **Save** ## Create the Secret in the Cluster @@ -60,8 +60,8 @@ kubectl create secret generic -n nephio-webui nephio-okta-oauth-client \ ## Enable the WebUI Auth Provider -The webui package has a function that will configure the package for authentication with different services. Edit the -`set-auth.yaml` file to set the `authProvider` field to `oidc` and the `oidcTokenProvider` to `okta`, or run these +The *webui* package has a function that will configure the package for authentication with different services. Edit the +*set-auth.yaml* file to set the authProvider field to *oidc* and the oidcTokenProvider to *okta*, or run the following commands: ```bash diff --git a/content/en/docs/guides/install-guides/webui.md b/content/en/docs/guides/install-guides/webui.md index 9c7a8c63..0c079c72 100644 --- a/content/en/docs/guides/install-guides/webui.md +++ b/content/en/docs/guides/install-guides/webui.md @@ -12,7 +12,7 @@ This page is draft and the separation of the content to different categories is ## Nephio WebUI -To install the WebUI, we simply install a different kpt package. First, we pull the package locally: +To install the WebUI, we simply install a different *kpt* package. First, we pull the package locally: ```bash kpt pkg get --for-deployment https://github.com/nephio-project/nephio-packages.git/nephio-webui@origin/v3.0.0 @@ -20,14 +20,14 @@ kpt pkg get --for-deployment https://github.com/nephio-project/nephio-packages.g Before we apply it to the cluster, however, we should configure it. -By default, it expects the webui to be reached via `http://localhost:7007`. If you plan to expose the webui via a load +By default, it expects the webui to be reached via *http://localhost:7007*. If you plan to expose the webui via a load balancer service instead, then you need to configure the scheme, hostname, port, and service. Note that if you wish to -use HTTPS, you should set the `scheme` to `https`, but you will need to terminate the TLS at the load balancer as the +use HTTPS, you should set the *scheme* to *https*, but you will need to terminate the TLS at the load balancer as the container currently only supports HTTP. This information is captured in the application ConfigMap for the webui, which is generated by a KRM function. We can -change the values in `nephio-webui/gen-configmap.yaml` just using a text editor (change the `hostname` and `port` values -under `params:`), and those will take effect later when we run `kpt fn render`. As an alternative to a text editor, you +change the values in the *nephio-webui/gen-configmap.yaml* just using a text editor (change the *hostname* and *port* values +under *params:*), and those will take effect later when we run `kpt fn render`. As an alternative to a text editor, you can run these commands: ```bash @@ -36,18 +36,18 @@ kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-kin kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-kind GenConfigMap -- 'by-path=params.port' 'put-value=PORT' ``` -If you want to expose the UI via a load balancer service, you can manually change the Service `type` to `LoadBalancer`, +If you want to expose the UI via a load balancer service, you can manually change the Service *type* to *LoadBalancer*, or run: ```bash kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-kind Service -- 'by-path=spec.type' 'put-value=LoadBalancer' ``` -In the default configuration, the Nephio WebUI *is wide open with no authentication*. The webui itself authenticates to +In the default configuration, the Nephio WebUI **is wide open with no authentication**. The webui itself authenticates to the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the webui is -*acting as a cluster admin*. +**acting as a cluster admin**. -This configuration is designed for *testing and development only*. You must not use this configuration in any other +This configuration is designed for **testing and development only**. You must not use this configuration in any other situation, and even for testing and development it must not be exposed on the internet (for example, via a LoadBalancer service). diff --git a/content/en/docs/guides/user-guides/controllers.md b/content/en/docs/guides/user-guides/controllers.md index 079e5e7e..ea3a13cb 100644 --- a/content/en/docs/guides/user-guides/controllers.md +++ b/content/en/docs/guides/user-guides/controllers.md @@ -35,9 +35,9 @@ The reconcilers below are currently deployed by default in the nephio controller To enable a particular reconciler, you pass an environment variable to the Nephio Controller at startup. The environment variable is of the form -`ENABLE_` where `` is the name of the reconciler to -be enabled in upper case. Therefore, to enable the `bootstrap-packages` reconciler, -pass the `ENABLE_BOOTSTRAPPACKAGES` to the nephio controller. Reconcilers are +*ENABLE_\* where *\* is the name of the reconciler to +be enabled in upper case. Therefore, to enable the bootstrap-packages reconciler, +pass the ENABLE_BOOTSTRAPPACKAGES to the nephio controller. Reconcilers are disabled by default. diff --git a/content/en/docs/guides/user-guides/exercise-1-free5gc.md b/content/en/docs/guides/user-guides/exercise-1-free5gc.md index 8025bcb9..a372d5ce 100644 --- a/content/en/docs/guides/user-guides/exercise-1-free5gc.md +++ b/content/en/docs/guides/user-guides/exercise-1-free5gc.md @@ -41,7 +41,7 @@ operator translates that into increased memory and CPU requirements for the unde To perform these exercises, you will need: -- Access to the installed demo VM environment and can login as the `ubuntu` user to have access to the necessary files. +- Access to the installed demo VM environment and can login as the ubuntu user to have access to the necessary files. - Access to the Nephio UI as described in the installation guide Access to Gitea, used in the demo environment as the Git provider, is optional. Later in the exercises, you will also @@ -59,8 +59,8 @@ Use the session just started on the VM to run these commands: {{% alert title="Note" color="primary" %}} -After fresh `docker` install, verify `docker` supplementary group is loaded by executing `id | grep docker`. -If not, logout and login to the VM or execute the `newgrp docker` to ensure the `docker` supplementary group is loaded. +After fresh docker install, verify docker supplementary group is loaded by executing `id | grep docker`. +If not, logout and login to the VM or execute the `newgrp docker` to ensure the docker supplementary group is loaded. {{% /alert %}} @@ -90,7 +90,7 @@ Since those are Ready, you can deploy a package from the [catalog-infra-capi](https://github.com/nephio-project/catalog/tree/main/infra/capi) repository into the mgmt repository. To do this, you retrieve the Package Revision name using `porchctl rpkg get`, clone that specific Package Revision via the `porchctl rpkg clone` command, then propose and approve the resulting package revision. You want to -use the latest revision of the nephio-workload-cluster package, which you can get with the command below (your latest +use the latest revision of the *nephio-workload-cluster* package, which you can get with the command below (your latest revision may be different): ```bash @@ -107,8 +107,8 @@ catalog-infra-capi-b0ae9512aab3de73bbae623a3b554ade57e15596 nephio-workload-cl ``` -Then, use the NAME from that in the `clone` operation, and the resulting PackageRevision name to perform the `propose` -and `approve` operations: +Then, use the NAME from that in the clone operation, and the resulting PackageRevision name to perform the propose +and approve operations: ```bash porchctl rpkg clone -n default catalog-infra-capi-b0ae9512aab3de73bbae623a3b554ade57e15596 --repository mgmt regional @@ -124,7 +124,7 @@ mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 created Next, you will want to ensure that the new Regional cluster is labeled as regional. Since you are using the CLI, you will need to pull the package out, modify it, and then push the updates back to the Draft revision. You will use `kpt` -and the `set-labels` function to do this. +and the set-labels function to do this. To pull the package to a local directory, use the `rpkg pull` command: @@ -132,7 +132,7 @@ To pull the package to a local directory, use the `rpkg pull` command: porchctl rpkg pull -n default mgmt-08c26219f9879acdefed3469f8c3cf89d5db3868 regional ``` -The package is now in the `regional` directory. So you can execute the `set-labels` function against the package +The package is now in the *regional* directory. So you can execute the set-labels function against the package imperatively, using `kpt fn eval`: ```bash @@ -150,7 +150,7 @@ The output is similar to: ``` -If you wanted to, you could have used the `--save` option to add the `set-labels` call to the package pipeline. This +If you wanted to, you could have used the --save option to add the set-labels call to the package pipeline. This would mean that function gets called whenever the server saves the package. If you added new resources later, they would also get labeled. @@ -219,7 +219,7 @@ regional Provisioned 52m v1.26.3 ``` -To access the API server of that cluster, you need to retrieve the `kubeconfig` file by pulling it from the Kubernetes +To access the API server of that cluster, you need to retrieve the *kubeconfig* file by pulling it from the Kubernetes Secret and decode the base64 encoding: ```bash @@ -268,7 +268,7 @@ regional-md-0-m6cr5-wtzlx regional 1 1 1 5m36s v1 ## Step 3: Deploy two Edge clusters -Next, you can deploy two Edge clusters by applying the PackageVariantSet that can be found in the `tests` directory: +Next, you can deploy two Edge clusters by applying the PackageVariantSet that can be found in the *tests* directory: ```bash kubectl apply -f test-infra/e2e/tests/free5gc/002-edge-clusters.yaml @@ -302,10 +302,10 @@ regional-md-0-lvmvm-8msw6 regional 1 1 1 143m v1. This is equivalent to doing the same `kpt` commands used earlier for the Regional cluster, except that it uses the PackageVariantSet controller, which is running in the Nephio Management cluster. It will clone the package for each -entry in the field `packageNames` in the PackageVariantSet. You can observe the progress by looking at the UI, or by +entry in the field packageNames in the PackageVariantSet. You can observe the progress by looking at the UI, or by using `kubectl` to monitor the various package variants, package revisions, and KinD clusters. -To access the API server of these clusters, you will need to get the `kubeconfig` file. To retrieve the file, you pull +To access the API server of these clusters, you will need to get the *kubeconfig* file. To retrieve the file, you pull it from the Kubernetes Secret and decode the base64 encoding: ```bash @@ -315,7 +315,7 @@ export KUBECONFIG=$HOME/.kube/config:$HOME/.kube/regional-kubeconfig:$HOME/.kube ``` To retain the KUBECONFIG environment variable permanently across sessions for the -user, add it to the `~/.bash_profile` and source the `~/.bash_profile` file +user, add it to the *~/.bash_profile* and source the *~/.bash_profile* file ```bash echo "export KUBECONFIG=$HOME/.kube/config:$HOME/.kube/regional-kubeconfig:$HOME/.kube/edge01-kubeconfig:$HOME/.kube/edge02-kubeconfig" >> ~/.bash_profile source ~/.bash_profile @@ -389,7 +389,7 @@ packagevariant.config.porch.kpt.dev/network created ``` -Then you will create appropriate `Secret` to make sure that Nephio can authenticate to the external backend. +Then you will create appropriate Secret to make sure that Nephio can authenticate to the external backend. ```bash kubectl apply -f test-infra/e2e/tests/free5gc/002-secret.yaml @@ -424,7 +424,7 @@ rawtopology.topo.nephio.org/nephio created While the Edge clusters are deploying (which will take 5-10 minutes), you can install the free5GC functions other than SMF, AMF, and UPF. For this, you will use the Regional cluster. Since these are all installed with a single package, you -can use the UI to pick the `free5gc-cp` package from the `free5gc-packages` repository and clone it to the `regional` +can use the UI to pick the *free5gc-cp* package from the *free5gc-packages* repository and clone it to the *regional* repository (you could have also used the CLI). ![Install free5gc - Step 1](/static/images/user-guides/free5gc-cp-1.png) @@ -433,8 +433,8 @@ repository (you could have also used the CLI). ![Install free5gc - Step 3](/static/images/user-guides/free5gc-cp-3.png) -Click through the "Next" button until you are through all the steps, then click "Add Deployment". On the next screen, -click "Propose", and then "Approve". +Click through the **Next** button until you are through all the steps, then click **Add Deployment**. On the next screen, +click **Propose**, and then **Approve**. ![Install free5gc - Step 4](/static/images/user-guides/free5gc-cp-4.png) @@ -522,7 +522,7 @@ statefulset.apps/mongodb 1/1 3m31s Now you will need to deploy the free5GC operator across all of the Workload clusters (regional and edge). To do this, you use another PackageVariantSet. This one uses an objectSelector to select the WorkloadCluster resources previously -added to the Management cluster when you had deployed the nephio-workload-cluster packages (manually as well as via +added to the Management cluster when you had deployed the *nephio-workload-cluster* packages (manually as well as via PackageVariantSet). ```bash @@ -539,7 +539,7 @@ packagevariantset.config.porch.kpt.dev/free5gc-operator created ## Step 6: Check free5GC Operator Deployment -Within five minutes of applying the free5GC Operator YAML file, you should see `free5gc` namespaces on your regional and +Within five minutes of applying the free5GC Operator YAML file, you should see free5gc namespaces on your regional and edge clusters: ```bash @@ -749,16 +749,16 @@ The output is similar to: ## Step 8: Deploy UERANSIM -The UERANSIM package can be deployed to the edge01 cluster, where it will simulate a gNodeB and UE. Just like our other +The *UERANSIM* package can be deployed to the edge01 cluster, where it will simulate a gNodeB and UE. Just like our other packages, UERANSIM needs to be configured to attach to the correct networks and use the correct IP address. Thus, you use our standard specialization techniques and pipeline to deploy UERANSIM, just like the other network functions. However, before you do that, let us register the UE with free5GC as a subscriber. You will use the free5GC Web UI to do -this. To access it, you need to open another port forwarding session. Assuming you have the `regional-kubeconfig` file +this. To access it, you need to open another port forwarding session. Assuming you have the *regional-kubeconfig* file you created earlier in your home directory, you need to establish another ssh session from your workstation to the VM, port forwarding port 5000. -Before moving on to the new terminal, let's copy `regional-kubeconfig` to the home directory: +Before moving on to the new terminal, let's copy regional-kubeconfig to the home directory: ```bash cp $HOME/.kube/regional-kubeconfig . @@ -838,7 +838,7 @@ Our DNN does not actually provide access to the internet, so you won't be able t In this step, you will change the capacity requirements for the UPF and SMF, and see how the operator reconfigures the Kubernetes resources used by the network functions. -The capacity requirements are captured in a custom resource (capacity.yaml) within the deployed package. You can edit +The capacity requirements are captured in a custom resource (*capacity.yaml*) within the deployed package. You can edit this value with the CLI, or use the web interface. Both options lead to the same result, but using the web interface is faster. First, you will vertically scale the UPF using the CLI. @@ -880,7 +880,7 @@ choice (in the example you can use /tmp/upf-scale-package). porchctl rpkg pull -n default edge01-40c616e5d87053350473d3ffa1387a9a534f8f42 /tmp/upf-scale-package ``` You can inspect the contents of the package in the chosen directory. The UPF configuration is located in the -capacity.yaml file. +*capacity.yaml* file. ```bash cat /tmp/upf-scale-package/capacity.yaml @@ -904,8 +904,8 @@ spec: ``` -The contents of the package will be mutated using kpt functions to adjust the UPF configuration, however you can also -manually edit the file. Apply the kpt functions to the contents of the kpt package with a new value for the throughputs +The contents of the package will be mutated using *kpt* functions to adjust the UPF configuration, however you can also +manually edit the file. Apply the *kpt* functions to the contents of the kpt package with a new value for the throughputs of your choice. ```bash @@ -1024,17 +1024,17 @@ After the package is approved, the results can be observed in Nephio Web UI. Hea Inside the package, you can see that the throughput values for UPF have been modified, reflecting the changes you made with the CLI. -You can also scale NFs vertically using the Nephio Web UI. For practice you can scale the UPF on the second edge cluster. Once again, navigate to the Web UI and choose the `edge02` repository in the Deployments section. +You can also scale NFs vertically using the Nephio Web UI. For practice you can scale the UPF on the second edge cluster. Once again, navigate to the Web UI and choose the **edge02** repository in the Deployments section. ![Edge02 Deployments](/static/images/user-guides/UPF-Capacity-5.png) -Select the `free5gc-upf` deployment, and then `View draft revision`. +Select the **free5gc-upf** deployment, and then **View draft revision**. ![UPF Deployment in edge02](/static/images/user-guides/UPF-Capacity-6.png) ![First revision](/static/images/user-guides/UPF-Capacity-7.png) -Edit the draft revision, and modify the `Capacity.yaml` file. +Edit the draft revision, and modify the *Capacity.yaml* file. ![Edit the revision](/static/images/user-guides/UPF-Capacity-8.png) @@ -1048,6 +1048,6 @@ After saving the changes to the file, propose the draft package and approve it. ![New revision](/static/images/user-guides/UPF-Capacity-12.png) -After a few minutes, the revision for the UPF deployment will change, and the changes will be reflected in the `edge-02` cluster. +After a few minutes, the revision for the UPF deployment will change, and the changes will be reflected in the edge-02 cluster. **NOTE**: You will observe that the UPF NFDeployment on the workload clusters is updated and synced with Gitea. The UPF pod will not reflect the new information. This is because the Nephio free5gc operator is not updating the pod with new configuration. diff --git a/content/en/docs/guides/user-guides/exercise-2-oai.md b/content/en/docs/guides/user-guides/exercise-2-oai.md index cf7b90a8..b2d405e8 100644 --- a/content/en/docs/guides/user-guides/exercise-2-oai.md +++ b/content/en/docs/guides/user-guides/exercise-2-oai.md @@ -34,7 +34,7 @@ The network configuration is illustrated in the following figure: To perform these exercises, you will need: -- Access to the installed demo VM environment and can login as the `ubuntu` user to have access to the necessary files. +- Access to the installed demo VM environment and can login as the ubuntu user to have access to the necessary files. - Access to the Nephio UI as described in the installation guide Access to Gitea, used in the demo environment as the Git provider, is optional. @@ -50,8 +50,8 @@ Use the session just started on the VM to run these commands: {{% alert title="Note" color="primary" %}} -After fresh `docker` install, verify `docker` supplementary group is loaded by executing `id | grep docker`. -If not, logout and login to the VM or execute the `newgrp docker` to ensure the `docker` supplementary group is loaded. +After fresh docker install, verify docker supplementary group is loaded by executing `id | grep docker`. +If not, logout and login to the VM or execute the `newgrp docker` to ensure the docker supplementary group is loaded. {{% /alert %}} @@ -77,7 +77,7 @@ oai-core-packages git Package false True https://github ``` -Since those are Ready, you can deploy packages from these repositories. You can use our pre-defined `PackageVariantSets` for creating workload clusters +Since those are Ready, you can deploy packages from these repositories. You can use our pre-defined *PackageVariantSets* for creating workload clusters ```bash kubectl apply -f test-infra/e2e/tests/oai/001-infra.yaml @@ -93,15 +93,15 @@ packagevariantset.config.porch.kpt.dev/oai-edge-clusters created ``` -It will take around 15 mins to create the three clusters. You can check the progress by looking at commits made in gitea `mgmt` and `mgmt-staging` repository. After couple of minutes you should see three independent repositories (Core, Regional and Edge) for each workload cluster. +It will take around 15 mins to create the three clusters. You can check the progress by looking at commits made in gitea *mgmt* and *mgmt-staging* repository. After couple of minutes you should see three independent repositories (Core, Regional and Edge) for each workload cluster. -You can also look at the state of `packagerevisions` for the three packages. You can use the below command +You can also look at the state of packagerevisions for the three packages. You can use the below command ```bash kubectl get packagerevisions | grep -E 'core|regional|edge' | grep mgmt ``` -While you are checking you will see `LIFECYCLE` will change from Draft to Published. Once packages are Published then the clusters will start getting deployed. +While you are checking you will see *LIFECYCLE* will change from Draft to Published. Once packages are Published then the clusters will start getting deployed. ## Step 2: Check the status of the workload clusters @@ -125,7 +125,7 @@ regional docker Provisioned 34m v1.26.3 ``` -To access the API server of that cluster, you need to retrieve the `kubeconfig` file by pulling it from the Kubernetes Secret and decode the base64 encoding: +To access the API server of that cluster, you need to retrieve the *kubeconfig* file by pulling it from the Kubernetes Secret and decode the base64 encoding: ```bash kubectl get secret core-kubeconfig -o jsonpath='{.data.value}' | base64 -d > $HOME/.kube/core-kubeconfig @@ -134,7 +134,7 @@ kubectl get secret edge-kubeconfig -o jsonpath='{.data.value}' | base64 -d > $HO export KUBECONFIG=$HOME/.kube/config:$HOME/.kube/regional-kubeconfig:$HOME/.kube/core-kubeconfig:$HOME/.kube/edge-kubeconfig ``` -To retain the KUBECONFIG environment variable permanently across sessions for the user, add it to the `~/.bash_profile` and source the `~/.bash_profile` file +To retain the KUBECONFIG environment variable permanently across sessions for the user, add it to the *~/.bash_profile* and source the *~/.bash_profile* file You can then use it to access the Workload cluster directly: @@ -225,7 +225,7 @@ worker nodes. Finally, you want to configure the resource backend to be aware of these clusters. The resource backend is an IP address and VLAN index management system. It is included for demonstration purposes to show how Nephio package specialization can interact with external systems to fully configure packages. But it needs to be configured to match our topology. First, you will apply a package to define the high-level networks for attaching our workloads. The Nephio package specialization pipeline will determine the exact VLAN tags and IP addresses for those attachments based on the specific -clusters. There is a predefined PackageVariant in the tests directory for this: +clusters. There is a predefined *PackageVariant* in the tests directory for this: ```bash kubectl apply -f test-infra/e2e/tests/oai/001-network.yaml @@ -253,7 +253,7 @@ secret/srl.nokia.com created ``` -The predefined PackageVariant package defines certain resources that exist for the entire topology. However, you also need to configure the resource backend for our particular topology. This will likely be automated in the future, but for now you can just directly apply the configuration you have created that matches this test topology. Within this step also the credentials and information is provided to configure the network device, that aligns with the topology. +The predefined *PackageVariant* package defines certain resources that exist for the entire topology. However, you also need to configure the resource backend for our particular topology. This will likely be automated in the future, but for now you can just directly apply the configuration you have created that matches this test topology. Within this step also the credentials and information is provided to configure the network device, that aligns with the topology. ```bash ./test-infra/e2e/provision/hacks/network-topo.sh @@ -335,7 +335,7 @@ packagerevision.porch.kpt.dev/mgmt-staging-f1b8e75b6c87549d67037f784abc0083ac601 ## Step 3: Deploy Dependencies, MySQL database, OAI Core and RAN Operator in the Workload clusters -Now you will need to deploy the MySQL database required by OAI UDR network function, OAI Core and RAN operators across the Workload clusters. To do this, you use `PackageVariant` and `PackageVariantSet`. Later uses an objectSelector to select the WorkloadCluster resources previously added to the Management cluster when you had deployed the nephio-workload-cluster packages (manually as well as via PackageVariantSet). +Now you will need to deploy the MySQL database required by OAI UDR network function, OAI Core and RAN operators across the Workload clusters. To do this, you use *PackageVariant* and *PackageVariantSet*. Later uses an objectSelector to select the WorkloadCluster resources previously added to the Management cluster when you had deployed the *nephio-workload-cluster* packages (manually as well as via *PackageVariantSet*). ```bash kubectl apply -f test-infra/e2e/tests/oai/002-database.yaml @@ -356,7 +356,7 @@ packagevariant.config.porch.kpt.dev/oai-ran-operator-regional created ## Step 4: Check Database and Operator Deployment -Within five minutes of applying the RAN, Core Operator, and database Packages, you should see `oai-core` and `oai-cn-operators` namespaces on the Core workload cluster: +Within five minutes of applying the RAN, Core Operator, and database Packages, you should see oai-core and oai-cn-operators namespaces on the Core workload cluster: ```bash kubectl get ns --context core-admin@core @@ -382,7 +382,7 @@ resource-group-system Active 88m ``` -In the namespace `oai-core` you can check MySQL pod +In the namespace oai-core you can check MySQL pod ```bash kubectl get pods -n oai-core --context core-admin@core @@ -397,7 +397,7 @@ mysql-7dd4cc6945-lqwcv 1/1 Running 0 7m12s ``` -In the `oai-cn-operators` namespace you should see control plane network function operators +In the oai-cn-operators namespace you should see control plane network function operators ```bash kubectl get pods -n oai-cn-operators --context core-admin@core @@ -464,7 +464,7 @@ resource-group-system Active 97m ``` -In edge cluster in `oai-cn-operators` namespace you will see only oai-upf network function. +In edge cluster in oai-cn-operators namespace you will see only oai-upf network function. ```bash kubectl get pods -n oai-cn-operators --context edge-admin@edge @@ -481,7 +481,7 @@ oai-upf-operator-75cbc869cb-67lf9 1/1 Running 0 16m ## Step 5: Deploy the Core Network Functions -You can start by deploying the core network functions which the operator will instantiate. For now, you will use individual `PackageVariants` targeting the Core and Edge cluster. In the future, you could put all of these resources into +You can start by deploying the core network functions which the operator will instantiate. For now, you will use individual *PackageVariants* targeting the Core and Edge cluster. In the future, you could put all of these resources into yet-another-package - a "topology" package - and deploy them all as a unit. Or you can use a topology controller to create them. But for now, let's do each manually. ```bash @@ -501,7 +501,7 @@ packagevariant.config.porch.kpt.dev/oai-upf-edge created ``` -All the NFs will wait for NRF to come up and then they will register to NRF. SMF has a dependency on UPF which is described by `dependency.yaml` file in SMF package. It will wait till the time UPF is deployed. It takes around ~800 seconds for the whole core network to come up. NRF is exposing its service via metallb external ip-address. In case metallb ip-address pool is not properly defined in the previous section, then UPF will not be able to register to NRF and in this case SMF and UPF will not be able to communicate. +All the NFs will wait for NRF to come up and then they will register to NRF. SMF has a dependency on UPF which is described by *dependency.yaml* file in SMF package. It will wait till the time UPF is deployed. It takes around ~800 seconds for the whole core network to come up. NRF is exposing its service via metallb external ip-address. In case metallb ip-address pool is not properly defined in the previous section, then UPF will not be able to register to NRF and in this case SMF and UPF will not be able to communicate. ### Check Core Network Deployment @@ -574,11 +574,11 @@ content-length: 58 [2024-01-25 16:54:21.817] [upf_n4 ] [info] Received SX HEARTBEAT REQUEST ``` -In the logs you should see `Received SX HEARTBEAT REQUEST` statement. If that is present then SMF and UPF are sharing PFCP heartbeats. +In the logs you should see **Received SX HEARTBEAT REQUEST** statement. If that is present then SMF and UPF are sharing PFCP heartbeats. ## Step 6: Deploy RAN Network Functions -If the core network functions are running and configured properly then you can start by deploying RAN network function `PackageVariants`. +If the core network functions are running and configured properly then you can start by deploying RAN network function *PackageVariants*. ```bash kubectl create -f test-infra/e2e/tests/oai/004-ran-network.yaml @@ -679,7 +679,7 @@ The output is similar to: ## Step 7: Deploy UE -If all three links are configured then you can proceed with deploying the UE `PackageVariants` +If all three links are configured then you can proceed with deploying the UE *PackageVariants* ```bash kubectl create -f test-infra/e2e/tests/oai/005-ue.yaml diff --git a/content/en/docs/guides/user-guides/helm/flux-helm.md b/content/en/docs/guides/user-guides/helm/flux-helm.md index 8a0e2546..f60c610e 100644 --- a/content/en/docs/guides/user-guides/helm/flux-helm.md +++ b/content/en/docs/guides/user-guides/helm/flux-helm.md @@ -26,7 +26,7 @@ Then, we can utilize the flux Custom Resources defined in another test kpt packa Access the Nephio Web UI and execute the following: -We will deploy the `flux-helm-controllers` pkg from the `nephio-example-packages` repo to the `edge02` workload +We will deploy the *flux-helm-controllers* pkg from the *nephio-example-packages* repo to the *edge02* workload cluster. * **Step 1** @@ -41,8 +41,8 @@ cluster. ![Install flux controllers - Step 3](/static/images/user-guides/flux-controller-selection.png) -Click through the `Next` button until you are through all the steps, leaving all options as `default`, then click -`Create Deployment`. +Click through the ***Next** button until you are through all the steps, leaving all options as default, then click +**Create Deployment**. * **Step 4** @@ -53,11 +53,11 @@ resources to deploy the controllers. {{% alert title="Note" color="primary" %}} -We are deploying into the `flux-system` namespace by default. +We are deploying into the flux-system namespace by default. {{% /alert %}} -Finally, we need to `propose` and then `approve` the pkg to initialize the deployment. +Finally, we need to propose and then approve the pkg to initialize the deployment. * **Step 5** @@ -85,8 +85,8 @@ source-controller-5756bf7d48-hprkn 1/1 Running 0 6m20s ### Deploying the onlineboutique-flux pkg -To make the demo kpt packages available in Nephio, we need to register a new `External Blueprints`repository. We can do -this via kubectl towards the management cluster. +To make the demo kpt packages available in Nephio, we need to register a new *External Blueprints* repository. We can do +this via `kubectl` towards the management cluster. ```bash cat << EOF | kubectl apply -f - @@ -109,7 +109,7 @@ spec: EOF ``` -The new repository should now have been added to the `External Blueprints` section of the UI. +The new repository should now have been added to the **External Blueprints** section of the UI. ![External Blueprints UI](/static/images/user-guides/external-bp-repos.png) diff --git a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md index eb6c2e5a..9cd40c8a 100644 --- a/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md +++ b/content/en/docs/guides/user-guides/helm/helm-to-operator-codegen-sdk-user-guide.md @@ -269,7 +269,7 @@ INFO[0000] ConfigMap |10 ```
-The generated Go-Code would be written to the "outputs/generated_code.go" file +The generated Go-Code would be written to the *outputs/generated_code.go* file The Generated Go-Code shall contain the following functions: @@ -289,7 +289,7 @@ The Generated Go-Code shall contain the following functions: Please refer [here](https://book.kubebuilder.io/quick-start) to develop & deploy the operator. After the basic structure of the operator is created, users can proceed to add their business logic -The `CreateAll()` and `DeleteAll()` functions generated by the SDK can be leveraged for Day-0 resource deployments, allowing users to easily manage the creation and deletion of resources defined in the Helm chart. By integrating their business logic with these functions, users can ensure that their operator effectively handles resource lifecycle management and orchestration within a Kubernetes environment. +The CreateAll() and DeleteAll() functions generated by the SDK can be leveraged for Day-0 resource deployments, allowing users to easily manage the creation and deletion of resources defined in the Helm chart. By integrating their business logic with these functions, users can ensure that their operator effectively handles resource lifecycle management and orchestration within a Kubernetes environment. In the end, all the resources created could be checked by: `kubectl get pods -n free5gcns` diff --git a/content/en/docs/network-architecture/o-ran-integration.md b/content/en/docs/network-architecture/o-ran-integration.md index 36e7f4ee..aae9e30c 100644 --- a/content/en/docs/network-architecture/o-ran-integration.md +++ b/content/en/docs/network-architecture/o-ran-integration.md @@ -88,7 +88,7 @@ The Nephio ClusterClaim CR: The O-Cloud Cluster Template: - Supports installation of add-on features such as Multus networking that will require specific configuration handled through the configRefs CRDs. A configRef CR can contain both configuration that is fixed for the O-Cloud Cluster template as well as instance specific configuration that must be provided as user input. -- Is realized with a KPT package that contains the ClusterClaim CR manifest as well as the referred O2imsClusterParameters CR manifest and additional configuration data manifests +- Is realized with a *KPT* package that contains the ClusterClaim CR manifest as well as the referred O2imsClusterParameters CR manifest and additional configuration data manifests As of this release, the O-RAN Alliance has not specified O2ims provisioning interface, as such this pre-standardization version of the O2ims provisioning interface is KRM/CRD based where the: diff --git a/content/en/docs/porch/config-as-data.md b/content/en/docs/porch/config-as-data.md index 11bf7bdd..c7c5def4 100644 --- a/content/en/docs/porch/config-as-data.md +++ b/content/en/docs/porch/config-as-data.md @@ -12,7 +12,7 @@ This document provides background context for Package Orchestration, which is fu ## Configuration as Data -*Configuration as Data* is an approach to management of configuration (incl. +Configuration as Data is an approach to management of configuration (incl. configuration of infrastructure, policy, services, applications, etc.) which: * makes configuration data the source of truth, stored separately from the live @@ -28,7 +28,7 @@ configuration of infrastructure, policy, services, applications, etc.) which: ## Key Principles -A system based on CaD *should* observe the following key principles: +A system based on CaD should observe the following key principles: * secrets should be stored separately, in a secret-focused storage system ([example](https://cloud.google.com/secret-manager)) @@ -47,7 +47,7 @@ A system based on CaD *should* observe the following key principles: can be operated on by given code (functions) * finds and/or filters / queries / selects code (functions) that can operate on resource types contained within a body of configuration data -* *actuation* (reconciliation of configuration data with live state) is separate +* actuation (reconciliation of configuration data with live state) is separate from transformation of configuration data, and is driven by the declarative data model * transformations, particularly value propagation, are preferable to wholesale @@ -90,16 +90,16 @@ metadata, references, status conventions, etc. as the configuration serialization data model * uses [Kptfile](https://kpt.dev/reference/schema/kptfile/) to store package metadata * uses [ResourceList](https://kpt.dev/reference/schema/resource-list/) as a serialized package wire-format -* uses a function `ResourceList → ResultList` (`kpt` function) as the foundational, composable unit of +* uses a function `ResourceList → ResultList` (*kpt* function) as the foundational, composable unit of package-manipulation code (note that other forms of code can manipulate packages as well, i.e. UIs, custom algorithms not necessarily packaged and used as kpt functions) and provides the following basic functionality: -* load a serialized package from a repository (as `ResourceList`) (examples of repository may be one or more of: local +* load a serialized package from a repository (as ResourceList) (examples of repository may be one or more of: local HDD, Git repository, OCI, Cloud Storage, etc.) -* save a serialized package (as `ResourceList`) to a package repository -* evaluate a function on a serialized package (`ResourceList`) +* save a serialized package (as ResourceList) to a package repository +* evaluate a function on a serialized package (ResourceList) * [render](https://kpt.dev/book/04-using-functions/01-declarative-function-execution) a package (evaluate functions declared within the package itself) * create a new (empty) package @@ -115,7 +115,7 @@ The Config as Data approach enables some key value which is available in other configuration management approaches to a lesser extent or is not available at all. -*CaD* approach enables: +CaD approach enables: * simplified authoring of configuration using a variety of methods and sources * WYSIWYG interaction with configuration using a simple data serialization formation rather than a code-like format diff --git a/content/en/docs/porch/contributors-guide/_index.md b/content/en/docs/porch/contributors-guide/_index.md index 349a0af9..13c88779 100644 --- a/content/en/docs/porch/contributors-guide/_index.md +++ b/content/en/docs/porch/contributors-guide/_index.md @@ -7,7 +7,7 @@ description: ## Changing Porch API -If you change the API resources, in `api/porch/.../*.go`, update the generated code by running: +If you change the API resources, in *api/porch/.../*.go*, update the generated code by running: ```sh make generate @@ -17,23 +17,23 @@ make generate Porch comprises of several software components: -* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch +* [*api*](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch extension apiserver -* [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of - Porch `Repository` and `PackageRevision` custom resources. -* [apiserver](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST - handlers, Porch `main` function -* [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - +* [*porchctl*](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of + Porch Repository and PackageRevision custom resources. +* [*apiserver*](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST + handlers, Porch main function +* [*engine*](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - operations on package contents -* [func](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API -* [repository](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package -* [git](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository. -* [oci](https://github.com/nephio-project/porch/tree/main/pkg/oci): Integration with OCI repository. -* [cache](https://github.com/nephio-project/porch/tree/main/pkg/cache): Package caching. -* [controllers](https://github.com/nephio-project/porch/tree/main/controllers): `Repository` CRD. No controller; +* [*func*](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API +* [*repository*](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package +* [*git*](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository. +* [*oci*](https://github.com/nephio-project/porch/tree/main/pkg/oci): Integration with OCI repository. +* [*cache*](https://github.com/nephio-project/porch/tree/main/pkg/cache): Package caching. +* [*controllers*](https://github.com/nephio-project/porch/tree/main/controllers): Repository CRD. No controller; Porch apiserver watches these resources for changes as repositories are (un-)registered. -* [test](https://github.com/nephio-project/porch/tree/main/test): Test Git Server for Porch e2e testing, and - [e2e](https://github.com/nephio-project/porch/tree/main/test/e2e) tests. +* [*test*](https://github.com/nephio-project/porch/tree/main/test): Test Git Server for Porch e2e testing, and + [*e2e*](https://github.com/nephio-project/porch/tree/main/test/e2e) tests. ## Running Porch @@ -68,7 +68,7 @@ Follow the [Running Porch Locally](../running-porch/running-locally.md) guide to ## Debugging -To debug Porch, run Porch locally [running-locally.md](../running-porch/running-locally.md), exit porch server running +To debug Porch, run Porch locally [Running Porch Locally](../running-porch/running-locally.md), exit porch server running in the shell, and launch Porch under the debugger. VSCode debug session is pre-configured in [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json). @@ -89,7 +89,7 @@ Some useful code pointers: ## Running Tests All tests can be run using `make test`. Individual tests can be run using `go test`. -End-to-End tests assume that Porch instance is running and `KUBECONFIG` is configured +End-to-End tests assume that Porch instance is running and KUBECONFIG is configured with the instance. The tests will automatically detect whether they are running against Porch running on local machien or k8s cluster and will start Git server appropriately, then run test suite against the Porch instance. @@ -103,7 +103,7 @@ then run test suite against the Porch instance. * `make push-images`: builds and pushes Porch Docker images * `make deployment-config`: customizes configuration which installs Porch in k8s cluster with correct image names, annotations, service accounts. - The deployment-ready configuration is copied into `./.build/deploy` + The deployment-ready configuration is copied into *./.build/deploy* * `make deploy`: deploys Porch in the k8s cluster configured with current kubectl context * `make push-and-deploy`: builds, pushes Porch Docker images, creates deployment configuration, and deploys Porch * `make` or `make all`: builds and runs Porch [locally](../running-porch/running-locally.md) diff --git a/content/en/docs/porch/contributors-guide/dev-process.md b/content/en/docs/porch/contributors-guide/dev-process.md index ec84f685..821a6593 100644 --- a/content/en/docs/porch/contributors-guide/dev-process.md +++ b/content/en/docs/porch/contributors-guide/dev-process.md @@ -31,17 +31,17 @@ After issuing this command you are expected to start the porch API server locall The simplest way to run the porch API server is to launch it in a VSCode IDE, as described by the following process: -1. Open the `porch.code-workspace` file in the root of the porch git repo. +1. Open the *porch.code-workspace* file in the root of the porch git repo. -1. Edit your local `.vscode/launch.json` file as follows: Change the `--kubeconfig` argument of the `Launch Server` configuration to point to a KUBECONFIG file that is set to the kind cluster as the current context. +1. Edit your local *.vscode/launch.json* file as follows: Change the `--kubeconfig` argument of the Launch Server configuration to point to a *KUBECONFIG* file that is set to the kind cluster as the current context. {{% alert title="Note" color="primary" %}} - If your current KUBECONFIG environment variable already points to the porch-test kind cluster, then you don't have to touch anything. + If your current *KUBECONFIG* environment variable already points to the porch-test kind cluster, then you don't have to touch anything. {{% /alert %}} -1. Launch the Porch server locally in VSCode by selecting the "Launch Server" configuration on the VSCode "Run and Debug" window. For more information please refer to the [VSCode debugging documentation](https://code.visualstudio.com/docs/editor/debugging). +1. Launch the Porch server locally in VSCode by selecting the **Launch Server** configuration on the VSCode **Run and Debug** window. For more information please refer to the [VSCode debugging documentation](https://code.visualstudio.com/docs/editor/debugging). ### Check to ensure that the API server is serving requests: @@ -129,7 +129,7 @@ curl https://localhost:4443/apis/porch.kpt.dev/v1alpha1 -k ## Troubleshoot the porch controllers -There are several ways to develop, test and troubleshoot the porch controllers (i.e. PackageVariant, PackageVariantSet). In this chapter we describe an option where every other parts of porch is running in the porch-test kind cluster, but the process hosting all porch controllers is running locally on your machine. +There are several ways to develop, test and troubleshoot the porch controllers (i.e. *ackageVariant*, *PackageVariantSet*). In this chapter we describe an option where every other parts of porch is running in the porch-test kind cluster, but the process hosting all porch controllers is running locally on your machine. The following command will rebuild and deploy porch, except the porch-controllers component: @@ -137,7 +137,7 @@ The following command will rebuild and deploy porch, except the porch-controller make run-in-kind-no-controllers ``` -After issuing this command you are expected to start the porch controllers process locally on your machine (outside of the kind cluster); probably in your IDE, potentially in a debugger. If you are using VS Code you can use the "Launch Controllers" configuration that is defined in the [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json) file of the porch git repo. +After issuing this command you are expected to start the porch controllers process locally on your machine (outside of the kind cluster); probably in your IDE, potentially in a debugger. If you are using VS Code you can use the **Launch Controllers** configuration that is defined in the [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json) file of the porch git repo. ## Run the unit tests @@ -147,7 +147,7 @@ make test ## Run the end-to-end tests -To run the end-to-end tests against the Kubernetes API server where KUBECONFIG points to, simply issue: +To run the end-to-end tests against the Kubernetes API server where *KUBECONFIG* points to, simply issue: ```bash make test-e2e @@ -182,7 +182,7 @@ E2E=1 go test -v ./test/e2e/cli -run TestPorch/rpkg-lifecycle The `make run-in-kind`, `make run-in-kind-no-server` and `make run-in-kind-no-controller` commands can be executed right after each other. No clean-up or restart is required between them. The make scripts will intelligently do the necessary changes in your current porch deployment in kind (e.g. removing or re-adding the porch API server). -You can always find the configuration of your current deployment in `.build/deploy`. +You can always find the configuration of your current deployment in *.build/deploy*. You can always use `make test` and `make test-e2e` to test your current setup, no matter which of the above detailed configurations it is. diff --git a/content/en/docs/porch/contributors-guide/environment-setup-vm.md b/content/en/docs/porch/contributors-guide/environment-setup-vm.md index 4b4945dc..0a1e6245 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup-vm.md +++ b/content/en/docs/porch/contributors-guide/environment-setup-vm.md @@ -41,7 +41,7 @@ sudo usermod -a -G syslog ubuntu sudo usermod -a -G docker ubuntu ``` -3. Log out of your VM and log in again so that the group changes on the `ubuntu` user are picked up. +3. Log out of your VM and log in again so that the group changes on the *ubuntu* user are picked up. ```bash > exit @@ -51,7 +51,7 @@ sudo usermod -a -G docker ubuntu ubuntu adm dialout cdrom floppy sudo audio dip video plugdev syslog netdev lxd docker ``` -4. Install `go` so that you can build Porch on the VM: +4. Install *go* so that you can build Porch on the VM: ```bash wget -O - https://go.dev/dl/go1.22.5.linux-amd64.tar.gz | sudo tar -C /usr/local -zxvf - @@ -64,7 +64,7 @@ echo ' PATH="/usr/local/go/bin:$PATH"' >> ~/.profile echo 'fi' >> ~/.profile ``` -5. Log out of your VM and log in again so that the `go` is added to your path. Verify that `go` is in the path: +5. Log out of your VM and log in again so that the *go* is added to your path. Verify that *go* is in the path: ```bash > exit @@ -75,7 +75,7 @@ echo 'fi' >> ~/.profile go version go1.22.5 linux/amd64 ``` -6. Install `go delve` for debugging on the VM: +6. Install *go delve* for debugging on the VM: ```bash go install -v github.com/go-delve/delve/cmd/dlv@latest @@ -104,7 +104,7 @@ sed -i "s/^KIND_CONTEXT_NAME ?= porch-test$/KIND_CONTEXT_NAME ?= "$(kind get clu kubectl expose svc -n porch-system function-runner --name=xfunction-runner --type=LoadBalancer --load-balancer-ip='172.18.0.202' ``` -10. Set the `KUBECONFIG` and `FUNCTION_RUNNER_IP` environment variables in the `.profile` file +10. Set the KUBECONFIG and FUNCTION_RUNNER_IP environment variables in the *.profile* file You **must** do this step before connecting with VSCode because VSCode caches the environment on the server. If you want to change the values of these variables subsequently, you must restart the VM server. ```bash @@ -127,7 +127,7 @@ documentation. 1. Use the **Connect to a remote host** instructions on the [Remote Development using SSH](https://code.visualstudio.com/docs/remote/ssh) page to connect to your VM. -2. Click **Open Folder** and browse to the Porch code on the vm, `/home/ubuntu/git/github/nephio-project/porch` in this case: +2. Click **Open Folder** and browse to the Porch code on the vm, */home/ubuntu/git/github/nephio-project/porch* in this case: ![Browse to Porch code](/static/images/porch/contributor/01_VSCodeOpenPorchFolder.png) @@ -135,12 +135,12 @@ documentation. ![Porch code is open](/static/images/porch/contributor/02_VSCodeConnectedPorch.png) -4. We now need to install support for `go` debugging in VSCode. Trigger this by launching a debug configuration in VSCode. +4. We now need to install support for *go* debugging in VSCode. Trigger this by launching a debug configuration in VSCode. Here we use the **Launch Override Server** configuration. ![Launch the Override Server VSCode debug configuration](/static/images/porch/contributor/03_LaunchOverrideServer.png) -5. VSCode complains that `go` debugging is not supported, click the **Install go Extension** button. +5. VSCode complains that *go* debugging is not supported, click the **Install go Extension** button. ![VSCode go debugging not supported message](/static/images/porch/contributor/04_GoDebugNotSupportedPopup.png) diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 5d1e6ad9..58a153bf 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -20,16 +20,16 @@ plugin to connect to it. ## Extra steps for MacOS users -The script the `make deployment-config` target to generate the deployment files for porch. The scripts called by this -make target use recent `bash` additions. MacOS comes with `bash` 3.x.x +The script the make deployment-config target to generate the deployment files for porch. The scripts called by this +make target use recent *bash* additions. MacOS comes with *bash* 3.x.x -1. Install `bash` 4.x.x or better of `bash` using homebrew, see +1. Install *bash* 4.x.x or better of *bash* using homebrew, see [this this post for details](https://apple.stackexchange.com/questions/193411/update-bash-to-version-4-0-on-osx) -2. Ensure that `/opt/homebrew/bin` is earlier in your path than `/bin` and `/usr/bin` +2. Ensure that */opt/homebrew/bin* is earlier in your path than */bin* and */usr/bin* {{% alert title="Note" color="primary" %}} -The changes above **permanently** change the `bash` version for **all** applications and may cause side +The changes above **permanently** change the *bash* version for **all** applications and may cause side effects. {{% /alert %}} @@ -37,7 +37,7 @@ effects. ## Setup the environment automatically -The [`./scripts/setup-dev-env.sh`](https://github.com/nephio-project/porch/blob/main/scripts/setup-dev-env.sh) setup +The [*./scripts/setup-dev-env.sh*](https://github.com/nephio-project/porch/blob/main/scripts/setup-dev-env.sh) setup script automatically builds a porch development environment. {{% alert title="Note" color="primary" %}} @@ -50,9 +50,9 @@ to customize it to suit your needs. The setup script will perform the following steps: 1. Install a kind cluster. The name of the cluster is read from the PORCH_TEST_CLUSTER environment variable, otherwise - it defaults to `porch-test`. The configuration of the cluster is taken from + it defaults to porch-test. The configuration of the cluster is taken from [here](https://github.com/nephio-project/porch/blob/main/deployments/local/kind_porch_test_cluster.yaml). -1. Install the MetalLB load balancer into the cluster, in order to allow `LoadBalancer` typed Services to work properly. +1. Install the MetalLB load balancer into the cluster, in order to allow LoadBalancer typed Services to work properly. 1. Install the Gitea git server into the cluster. This can be used to test porch during development, but it is not used in automated end-to-end tests. Gitea is exposed to the host via port 3000. The GUI is accessible via , or (username: nephio, password: secret). @@ -63,7 +63,7 @@ The setup script will perform the following steps: {{% /alert %}} 1. Generate the PKI resources (key pairs and certificates) required for end-to-end tests. -1. Build the porch CLI binary. The result will be generated as `.build/porchctl`. +1. Build the porch CLI binary. The result will be generated as *.build/porchctl*. That's it! If you want to run the steps manually, please use the code of the script as a detailed description. @@ -72,7 +72,7 @@ script is interrupted for any reason, and you run it again it should effectively ## Extra manual steps -Copy the `.build/porchctl` binary (that was built by the setup script) to somewhere in your $PATH, or add the `.build` +Copy the *.build/porchctl* binary (that was built by the setup script) to somewhere in your $PATH, or add the *.build* directory to your PATH. ## Build and deploy porch @@ -143,7 +143,7 @@ external-blueprints git Package false True https://github.com/n management git Package false True http://172.18.255.200:3000/nephio/management.git ``` -You can also check the repositories using kubectl. +You can also check the repositories using *kubectl*. ```bash kubectl get repositories -n porch-demo diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index a687b658..ea6d3a96 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -8,7 +8,7 @@ description: ## Why Customers who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using -a [kpt](https://kpt.dev) CLI and kpt function ecosystem, including [functions catalog](https://catalog.kpt.dev/). +a [*kpt*](https://kpt.dev) CLI and *kpt* function ecosystem, including [functions catalog](https://catalog.kpt.dev/). Package authoring is possible using a variety of editors with [YAML](https://yaml.org/) support. That said, a delightful UI experience of WYSIWYG package authoring which supports broader package lifecycle, including package authoring with *guardrails*, approval workflow, package deployment, and more, is not yet available. @@ -20,40 +20,40 @@ building the delightful UI experience supporting the configuration lifecycle. This section briefly describes core concepts of package orchestration: -***Package***: Package is a collection of related configuration files containing configuration of [KRM][krm] -**resources**. Specifically, configuration packages are [kpt packages](https://kpt.dev/). +**Package**: Package is a collection of related configuration files containing configuration of [KRM][krm] +resources. Specifically, configuration packages are [*kpt* packages](https://kpt.dev/). -***Repository***: Repositories store packages or [functions][]. For example [git][] or [OCI][oci]. Functions may be +**Repository**: Repositories store packages or [functions][]. For example [git][] or [OCI][oci]. Functions may be associated with repositories to enforce constraints or invariants on packages (guardrails). ([more details](#repositories)) -Packages are sequentially ***versioned***; multiple versions of the same package may exist in a repository. +Packages are sequentially versioned; multiple versions of the same package may exist in a repository. [more details](#package-versioning)) -A package may have a link (URL) to an ***upstream package*** (a specific version) from which it was cloned. +A package may have a link (URL) to an upstream package (a specific version) from which it was cloned. ([more details](#package-relationships)) Package may be in one of several lifecycle stages: -* ***Draft*** - package is being created or edited. The package contents can be modified but package is not ready to be +* **Draft** - package is being created or edited. The package contents can be modified but package is not ready to be used (i.e. deployed) -* ***Proposed*** - author of the package proposed that the package be published -* ***Published*** - the changes to the package have been approved and the package is ready to be used. Published +* **Proposed** - author of the package proposed that the package be published +* **Published** - the changes to the package have been approved and the package is ready to be used. Published packages can be deployed or cloned -***Function*** (specifically, [KRM functions][krm functions]) can be applied to packages to mutate or validate resources +**Function** (specifically, [KRM functions][krm functions]) can be applied to packages to mutate or validate resources within them. Functions can be applied to a package to create specific package mutation while editing a package draft, -functions can be added to package's Kptfile [pipeline][], or associated with a repository to be applied to all packages +functions can be added to package's *Kptfile* [pipeline][], or associated with a repository to be applied to all packages on changes. ([more details](#functions)) -A repository can be designated as ***deployment repository***. *Published* packages in a deployment repository are +A repository can be designated as deployment repository. Published packages in a deployment repository are considered deployment-ready. ([more details](#deployment)) ## Core Components of Configuration as Data Implementation -The Core implementation of Configuration as Data, *CaD Core*, is a set of components and APIs which collectively enable: +The Core implementation of Configuration as Data, CaD Core, is a set of components and APIs which collectively enable: -* Registration of repositories (Git, OCI) containing kpt packages or functions, and discovery of packages and functions +* Registration of repositories (Git, OCI) containing *kpt* packages or functions, and discovery of packages and functions * Porcelain package lifecycle, including authoring, versioning, deletion, creation and mutations of a package draft, process of proposing the package draft, and publishing of the approved package. * Package lifecycle operations such as: @@ -73,7 +73,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [kpt][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [*kpt*][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle @@ -86,8 +86,8 @@ Concepts briefly introduced above are elaborated in more detail in this section. ### Repositories -[kpt][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI -support to kpt. Initially, the Package Orchestration service will prioritize integration with [git][], and support for +[*kpt*][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI +support to *kpt*. Initially, the Package Orchestration service will prioritize integration with [git][], and support for additional repository types may be added in the future as required. Requirements applicable to all repositories include: ability to store packages, their versions, and sufficient metadata @@ -126,8 +126,8 @@ We plan to use a simple integer sequence to represent package versions. ### Package Relationships -Kpt packages support the concept of ***upstream***. When a package is cloned from another, the new package -(called ***downstream*** package) maintains an upstream link to the specific version of the package from which it was +*kpt* packages support the concept of upstream. When a package is cloned from another, the new package +(called downstream package) maintains an upstream link to the specific version of the package from which it was cloned. If a new version of the upstream package becomes available, the upstream link can be used to [update](https://kpt.dev/book/03-packages/05-updating-a-package) the downstream package. @@ -140,11 +140,11 @@ others can be used as well. Here we highlight some key attributes of the deployment mechanism and its integration within the CaD Core: -* _Published_ packages in a deployment repository are considered ready to be deployed +* Published packages in a deployment repository are considered ready to be deployed * Config Sync supports deploying individual packages and whole repositories. For Git specifically that translates to a requirement to be able to specify repository, branch/tag/ref, and directory when instructing Config Sync to deploy a package. -* _Draft_ packages need to be identified in such a way that Config Sync can easily avoid deploying them. +* Draft packages need to be identified in such a way that Config Sync can easily avoid deploying them. * Config Sync needs to be able to pin to specific versions of deployable packages in order to orchestrate rollouts and rollbacks. This means it must be possible to GET a specific version of a package. * Config Sync needs to be able to discover when new versions are available for deployment. @@ -164,16 +164,16 @@ packages. Function can be: * applied imperatively to a package draft to perform specific mutation to the package's resources or meta-resources - (`Kptfile` etc.) -* registered in the package's `Kptfile` function pipeline as a *mutator* or *validator* in order to be automatically run + (*Kptfile* etc.) +* registered in the package's *Kptfile* function pipeline as a mutator or validator in order to be automatically run as part of package rendering -* registered at the repository level as *mutator* or *validator*. Such function then applies to all packages in the +* registered at the repository level as mutator or validator. Such function then applies to all packages in the repository and is evaluated whenever a change to a package in the repository occurs. ## Package Orchestration - Porch Having established the context of the CaD Core components and the overall architecture, the remainder of the document -will focus on **Porch** - Package Orchestration service. +will focus on Porch - Package Orchestration service. To reiterate the role of Package Orchestration service among the CaD Core components, it is: @@ -181,7 +181,7 @@ To reiterate the role of Package Orchestration service among the CaD Core compon * [Package Discovery](#package-discovery) * [Package Authoring](#package-authoring) and Lifecycle -In the following section we'll expand more on each of these areas. The term _client_ used in these sections can be +In the following section we'll expand more on each of these areas. The term *client* used in these sections can be either a person interacting with the UI such as a web application or a command-line tool, or an automated agent or process. @@ -209,7 +209,7 @@ The package discovery functionality of Package Orchestration service enables the * retrieve resources and metadata of an individual package, including latest version or any specific version or draft of a package, for the purpose of introspection of a single package or for comparison of contents of multiple versions of a package, or related packages -* enumerate _upstream_ packages available for creating (cloning) a _downstream_ package +* enumerate upstream packages available for creating (cloning) a downstream package * identify downstream packages that need to be upgraded after a change is made to an upstream package * identify all deployment-ready packages in a deployment repository that are ready to be synced to a deployment target by Config Sync @@ -223,28 +223,28 @@ The package discovery functionality of Package Orchestration service enables the The package authoring and lifecycle functionality of the package Orchestration service enables the client to: -* Create a package _draft_ via one of the following means: +* Create a package draft via one of the following means: - * an empty draft 'from scratch' (equivalent to [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/)) - * clone of an upstream package (equivalent to [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/)) from either a + * an empty draft 'from scratch' (equivalent to [`kpt pkg init`](https://kpt.dev/reference/cli/pkg/init/)) + * clone of an upstream package (equivalent to [`kpt pkg get`](https://kpt.dev/reference/cli/pkg/get/)) from either a registered upstream repository or from another accessible, unregistered, repository - * edit an existing package (similar to the CLI command(s) [kpt fn source](https://kpt.dev/reference/cli/fn/source/) or - [kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557)) + * edit an existing package (similar to the CLI command(s) [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/) or + [`kpt pkg pull`](https://github.com/GoogleContainerTools/kpt/issues/2557)) * roll back / restore a package to any of its previous versions - ([kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version) + ([`kpt pkg pull`](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version) -* Apply changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's +* Apply changes to a package draft. In general, mutations include adding/modifying/deleting any part of the package's contents. Some specific examples include: - * add/change/delete package metadata (i.e. some properties in the `Kptfile`) + * add/change/delete package metadata (i.e. some properties in the *Kptfile*) * add/change/delete resources in the package * add function mutators/validators to the package's [pipeline][] * invoke a function imperatively on the package draft to perform a desired mutation * add/change/delete sub-package * retrieve the contents of the package for arbitrary client-side mutations (equivalent to - [kpt fn source](https://kpt.dev/reference/cli/fn/source/)) + [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/)) * update/replace the package contents with new contents, for example results of a client-side mutations by a UI - (equivalent to [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/)) + (equivalent to [`kpt fn sink`](https://kpt.dev/reference/cli/fn/sink/)) * Rebase a package onto another upstream base package ([detail](https://github.com/GoogleContainerTools/kpt/issues/2548)) or onto a newer version of the same package (to @@ -254,9 +254,9 @@ The package authoring and lifecycle functionality of the package Orchestration s * merge conflicts, invalid package changes, guardrail violations * compliance of the drafted package with repository-wide invariants and guardrails -* Propose for a _draft_ package be _published_. -* Apply an arbitrary decision criteria, and by a manual or automated action, approve (or reject) proposal of a _draft_ - package to be _published_. +* Propose for a draft package be published. +* Apply an arbitrary decision criteria, and by a manual or automated action, approve (or reject) proposal of a draft + package to be published. * Perform bulk operations such as: * Assisted/automated update (upgrade, rollback) of groups of packages matching specific criteria (i.e. base package @@ -292,7 +292,7 @@ perform in order to satisfy requirements of the basic roles. For example, only p ### Porch Architecture -The Package Orchestration service, **Porch** is designed to be hosted in a [Kubernetes](https://kubernetes.io/) cluster. +The Package Orchestration service, Porch is designed to be hosted in a [Kubernetes](https://kubernetes.io/) cluster. The overall architecture is shown below, and includes also existing components (k8s apiserver and Config Sync). @@ -319,34 +319,34 @@ extension API server are: Resources implemented by Porch include: -* `PackageRevision` - represents the _metadata_ of the configuration package revision stored in a _package_ repository. -* `PackageRevisionResources` - represents the _contents_ of the package revision -* `Function` - represents a [KRM function][krm functions] discovered in a registered _function_ repository. +* **PackageRevision** - represents the metadata of the configuration package revision stored in a package repository. +* **PackageRevisionResources** - represents the contents of the package revision +* **Function** - represents a [KRM function][krm functions] discovered in a registered function repository. -Note that each configuration package revision is represented by a _pair_ of resources which each present a different +Note that each configuration package revision is represented by a pair of resources which each present a different view (or [representation][] of the same underlying package revision. -Repository registration is supported by a `Repository` [custom resource][crds]. +Repository registration is supported by a Repository [custom resource][crds]. -**Porch server** itself comprises several key components, including: +Porch server itself comprises several key components, including: -* The *Porch aggregated apiserver* which implements the integration into the main Kubernetes apiserver, and directly - serves API requests for the `PackageRevision`, `PackageRevisionResources` and `Function` resources. -* Package orchestration *engine* which implements the package lifecycle operations, and package mutation workflows -* *CaD Library* which implements specific package manipulation algorithms such as package rendering (evaluation of - package's function *pipeline*), initialization of a new package, etc. The CaD Library is shared with `kpt` +* The **Porch aggregated apiserver** which implements the integration into the main Kubernetes apiserver, and directly + serves API requests for the PackageRevision, PackageRevisionResources and Function resources. +* Package orchestration engine which implements the package lifecycle operations, and package mutation workflows +* **CaD Library** which implements specific package manipulation algorithms such as package rendering (evaluation of + package's function pipeline), initialization of a new package, etc. The CaD Library is shared with *kpt* where it likewise provides the core package manipulation algorithms. -* *Package cache* which enables both local caching, as well as abstract manipulation of packages and their contents +* **Package cache** which enables both local caching, as well as abstract manipulation of packages and their contents irrespectively of the underlying storage mechanism (Git, or OCI) -* *Repository adapters* for Git and OCI which implement the specific logic of interacting with those types of package +* **Repository adapters** for Git and OCI which implement the specific logic of interacting with those types of package repositories. -* *Function runtime* which implements support for evaluating [kpt functions][functions] and multi-tier cache of +* **Function runtime** which implements support for evaluating [*kpt* functions][functions] and multi-tier cache of functions to support low latency function evaluation #### Function Runner -**Function runner** is a separate service responsible for evaluating [kpt functions][functions]. Function runner exposes -a [gRPC](https://grpc.io/) endpoint which enables evaluating a kpt function on the provided configuration package. +Function runner is a separate service responsible for evaluating [**kpt** functions][functions]. Function runner exposes +a [gRPC](https://grpc.io/) endpoint which enables evaluating a *kpt* function on the provided configuration package. The gRPC technology was chosen for the function runner service because the [requirements](#grpc-api) that informed choice of KRM API for the Package Orchestration service do not apply. The function runner is an internal microservice, @@ -356,29 +356,29 @@ The function runner also maintains cache of functions to support low latency fun #### CaD Library -The [kpt](https://kpt.dev/) CLI already implements foundational package manipulation algorithms in order to provide the +The [*kpt*](https://*kpt*.dev/) CLI already implements foundational package manipulation algorithms in order to provide the command line user experience, including: -* [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/) - create an empty, valid, KRM package -* [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/) - create a downstream package by cloning an upstream package; +* [`kpt pkg init`](https://kpt.dev/reference/cli/pkg/init/) - create an empty, valid, KRM package +* [`kpt pkg get`](https://kpt.dev/reference/cli/pkg/get/) - create a downstream package by cloning an upstream package; set up the upstream reference of the downstream package -* [kpt pkg update](https://kpt.dev/reference/cli/pkg/update/) - update the downstream package with changes from new +* [`kpt pkg update`](https://kpt.dev/reference/cli/pkg/update/) - update the downstream package with changes from new version of upstream, 3-way merge -* [kpt fn eval](https://kpt.dev/reference/cli/fn/eval/) - evaluate a kpt function on a package -* [kpt fn render](https://kpt.dev/reference/cli/fn/render/) - render the package by executing the function pipeline of +* [`kpt fn eval`](https://kpt.dev/reference/cli/fn/eval/) - evaluate a *kpt* function on a package +* [`kpt fn render`](https://kpt.dev/reference/cli/fn/render/) - render the package by executing the function pipeline of the package and its nested packages -* [kpt fn source](https://kpt.dev/reference/cli/fn/source/) and [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/) - - read package from local disk as a `ResourceList` and write package represented as `ResourcesList` into local disk +* [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/) and [`kpt fn sink`](https://kpt.dev/reference/cli/fn/sink/) - + read package from local disk as a ResourceList and write package represented as ResourcesList into local disk The same set of primitives form the foundational building blocks of the package orchestration service. Further, the package orchestration service combines these primitives into higher-level operations (for example, package orchestrator renders packages automatically on changes, future versions will support bulk operations such as upgrade of multiple packages, etc). -The implementation of the package manipulation primitives in kpt was refactored (with initial refactoring completed, and +The implementation of the package manipulation primitives in *kpt* was refactored (with initial refactoring completed, and more to be performed as needed) in order to: -* create a reusable CaD library, usable by both kpt CLI and Package Orchestration service +* create a reusable CaD library, usable by both *kpt* CLI and Package Orchestration service * create abstractions for dependencies which differ between CLI and Porch, most notable are dependency on Docker for function evaluation, and dependency on the local file system for package rendering. @@ -389,14 +389,14 @@ Over time, the CaD Library will provide the package manipulation primitives: * perform 3-way merge (update) * render - core package rendering algorithm using a pluggable function evaluator to support: - * function evaluation via Docker (used by kpt CLI) + * function evaluation via Docker (used by *kpt* CLI) * function evaluation via an RPC to a service or appropriate function sandbox * high-performance evaluation of trusted, built-in, functions without sandbox * heal configuration (restore comments after lossy transformation) -and both kpt CLI and Porch will consume the library. This approach will allow leveraging the investment already made -into the high quality package manipulation primitives, and enable functional parity between KPT CLI and Package +and both *kpt* CLI and Porch will consume the library. This approach will allow leveraging the investment already made +into the high quality package manipulation primitives, and enable functional parity between *KPT* CLI and Package Orchestration service. ## User Guide diff --git a/content/en/docs/porch/package-variant.md b/content/en/docs/porch/package-variant.md index 7ef66109..d6b3995a 100644 --- a/content/en/docs/porch/package-variant.md +++ b/content/en/docs/porch/package-variant.md @@ -36,20 +36,20 @@ variants. These are designed to address several different dimensions of scalabil ## Core Concepts -For this solution, "workloads" are represented by packages. "Package" is a more general concept, being an arbitrary +For this solution, workloads are represented by packages. Package is a more general concept, being an arbitrary bundle of resources, and therefore is sufficient to solve the originally stated problem. -The basic idea here is to introduce a PackageVariant resource that manages the derivation of a variant of a package from +The basic idea here is to introduce a *PackageVariant* resource that manages the derivation of a variant of a package from the original source package, and to manage the evolution of that variant over time. This effectively automates the -human-centered process for variant creation one might use with `kpt`: +human-centered process for variant creation one might use with *kpt*: 1. Clone an upstream package locally 1. Make changes to the local package, setting values in resources and executing KRM functions 1. Push the package to a new repository and tag it as a new version -Similarly, PackageVariant can manage the process of updating a package when a new version of the upstream package is +Similarly, *PackageVariant* can manage the process of updating a package when a new version of the upstream package is published. In the human-centered workflow, a user would use `kpt pkg update` to pull in changes to their derivative -package. When using a PackageVariant resource, the change would be made to the upstream specification in the resource, +package. When using a *PackageVariant* resource, the change would be made to the upstream specification in the resource, and the controller would propose a new Draft package reflecting the outcome of `kpt pkg update`. By automating this process, we open up the possibility of performing systematic changes that tie back to our different @@ -65,22 +65,22 @@ across packages but configured as needed for the specific package, are used to i package. This decouples authoring of the packages, creation of the input model, and deploy-time use of that input model within the packages, allowing those activities to be performed by different teams or organizations. -We refer to the mechanism described above as *configuration injection*. It enables dynamic, context-aware creation of +We refer to the mechanism described above as configuration injection. It enables dynamic, context-aware creation of variants. Another way to think about it is as a continuous reconciliation, much like other Kubernetes controllers. In -this case, the inputs are a parent package `P` and a context `C` (which may be a collection of many independent -resources), with the output being the derived package `D`. When a new version of `C` is created by updates to in-cluster -resources, we get a new revision of `D`, customized based upon the updated context. Similarly, the user (or an -automation) can monitor for new versions of `P`; when one arrives, the PackageVariant can be updated to point to that -new version, resulting in a newly proposed Draft of `D`, updated to reflect the upstream changes. This will be explained +this case, the inputs are a parent package *P* and a context *C* (which may be a collection of many independent +resources), with the output being the derived package *D*. When a new version of *C* is created by updates to in-cluster +resources, we get a new revision of *D*, customized based upon the updated context. Similarly, the user (or an +automation) can monitor for new versions of *P*; when one arrives, the *PackageVariant* can be updated to point to that +new version, resulting in a newly proposed Draft of *D*, updated to reflect the upstream changes. This will be explained in more detail below. -This proposal also introduces a way to "fan-out", or create multiple PackageVariant resources declaratively based upon a -list or selector, with the PackageVariantSet resource. This is combined with the injection mechanism to enable +This proposal also introduces a way to "fan-out", or create multiple *PackageVariant* resources declaratively based upon a +list or selector, with the *PackageVariantSet* resource. This is combined with the injection mechanism to enable generation of large sets of variants that are specialized to a particular target repository, cluster, or other resource. ## Basic Package Cloning -The PackageVariant resource controls the creation and lifecycle of a variant of a package. That is, it defines the +The *PackageVariant* resource controls the creation and lifecycle of a variant of a package. That is, it defines the original (upstream) package, the new (downstream) package, and the changes (mutations) that need to be made to transform the upstream into the downstream. It also allows the user to specify policies around adoption, deletion, and update of package revisions that are under the control of the package variant controller. @@ -101,30 +101,30 @@ variant control will do, depending upon the specified deletion policy. ### PackageRevision Metadata -The package variant controller utilizes Porch APIs. This means that it is not just doing a `clone` operation, but in -fact creating a Porch PackageRevision resource. In particular, that resource can contain Kubernetes metadata that is +The package variant controller utilizes Porch APIs. This means that it is not just doing a clone operation, but in +fact creating a Porch *PackageRevision* resource. In particular, that resource can contain Kubernetes metadata that is not part of the package as stored in the repository. -Some of that metadata is necessary for the management of the PackageRevision by the package variant controller - for -example, the owner reference indicating which PackageVariant created the PackageRevision. These are not under the user's -control. However, the PackageVariant resource does make the annotations and labels of the PackageRevision available as -values that may be controlled during the creation of the PackageRevision. This can assist in additional automation +Some of that metadata is necessary for the management of the *PackageRevision* by the package variant controller - for +example, the owner reference indicating which *PackageVariant* created the *PackageRevision*. These are not under the user's +control. However, the *PackageVariant* resource does make the annotations and labels of the *PackageRevision* available as +values that may be controlled during the creation of the *PackageRevision*. This can assist in additional automation workflows. ## Introducing Variance -Just cloning is not that interesting, so the PackageVariant resource also allows you to control various ways of mutating +Just cloning is not that interesting, so the *PackageVariant* resource also allows you to control various ways of mutating the original package to create the variant. ### Package Context[^porch17] -Every kpt package that is fetched with `--for-deployment` will contain a ConfigMap called `kptfile.kpt.dev`. +Every *kpt* package that is fetched with `--for-deployment` will contain a ConfigMap called *kptfile.kpt.dev*. Analogously, when Porch creates a package in a deployment repository, it will create this ConfigMap, if it does not -already exist. Kpt (or Porch) will automatically add a key `name` to the ConfigMap data, with the value of the package -name. This ConfigMap can then be used as input to functions in the Kpt function pipeline. +already exist. *Kpt* (or Porch) will automatically add a key name to the ConfigMap data, with the value of the package +name. This ConfigMap can then be used as input to functions in the *kpt* function pipeline. This process holds true for package revisions created via the package variant controller as well. Additionally, the -author of the PackageVariant resource can specify additional key-value pairs to insert into the package context, as +author of the *PackageVariant* resource can specify additional key-value pairs to insert into the package context, as shown in *Figure 2*. | ![Figure 2: Package Context Mutation](/static/images/porch/packagevariant-context.png) | @@ -137,8 +137,8 @@ than simple key/value pairs. ### Kptfile Function Pipeline Editing[^porch18] -In the manual workflow, one of the ways we edit packages is by running KRM functions imperatively. PackageVariant offers -a similar capability, by allowing the user to add functions to the beginning of the downstream package `Kptfile` +In the manual workflow, one of the ways we edit packages is by running KRM functions imperatively. *PackageVariant* offers +a similar capability, by allowing the user to add functions to the beginning of the downstream package *Kptfile* mutators pipeline. These functions will then execute before the functions present in the upstream pipeline. It is not exactly the same as running functions imperatively, because they will also be run in every subsequent execution of the downstream package function pipeline. But it can achieve the same goals. @@ -147,9 +147,9 @@ For example, consider an upstream package that includes a Namespace resource. In workload may not have the permissions to provision cluster-scoped resources like namespaces. This means that they would not be able to use this upstream package without removing the Namespace resource (assuming that they only have access to a pipeline that deploys with constrained permissions). By adding a function that removes Namespace resources, and a call -to `set-namespace`, they can take advantage of the upstream package. +to set-namespace, they can take advantage of the upstream package. -Similarly, the Kptfile pipeline editing feature provides an easy mechanism for the deployer to create and set the +Similarly, the *Kptfile* pipeline editing feature provides an easy mechanism for the deployer to create and set the namespace if their downstream package application pipeline allows it, as seen in *Figure 3*.[^setns] | ![Figure 3: KRM Function Pipeline Editing](/static/images/porch/packagevariant-function.png) | @@ -159,7 +159,7 @@ namespace if their downstream package application pipeline allows it, as seen in ### Configuration Injection[^porch18] Adding values to the package context or functions to the pipeline works for configuration that is under the control of -the creator of the PackageVariant resource. However, in more advanced use cases, we may need to specialize the package +the creator of the *PackageVariant* resource. However, in more advanced use cases, we may need to specialize the package based upon other contextual information. This particularly comes into play when the user deploying the workload does not have direct control over the context in which it is being deployed. For example, one part of the organization may manage the infrastructure - that is, the cluster in which we are deploying the workload - and another part the actual @@ -171,13 +171,13 @@ will use information specific to this instance of the package to lookup a resour information into the package. Of course, the package has to be ready to receive this information. So, there is a protocol for facilitating this dance: -- Packages may contain resources annotated with `kpt.dev/config-injection` -- Often, these will also be `config.kubernetes.io/local-config` resources, as they are likely just used by local +- Packages may contain resources annotated with *kpt.dev/config-injection* +- Often, these will also be *config.kubernetes.io/local-config* resources, as they are likely just used by local functions as input. But this is not mandatory. - The package variant controller will look for any resource in the Kubernetes cluster matching the Group, Version, and - Kind of the package resource, and satisfying the *injection selector*. -- The package variant controller will copy the `spec` field from the matching in-cluster resource to the in-package - resource, or the `data` field in the case of a ConfigMap. + Kind of the package resource, and satisfying the injection selector. +- The package variant controller will copy the spec field from the matching in-cluster resource to the in-package + resource, or the data field in the case of a ConfigMap. | ![Figure 4: Configuration Injection](/static/images/porch/packagevariant-config-injection.png) | | :---: | @@ -185,7 +185,7 @@ protocol for facilitating this dance: {{% alert title="Note" color="primary" %}} -Because we are injecting data *from the Kubernetes cluster*, we can also monitor that data for changes. For +Because we are injecting data from the Kubernetes cluster, we can also monitor that data for changes. For each resource we inject, the package variant controller will establish a Kubernetes "watch" on the resource (or perhaps on the collection of such resources). A change to that resource will result in a new Draft package with the updated configuration injected. @@ -201,27 +201,27 @@ API definition. The package variant controller allows you to specific a specific upstream package revision to clone, or you can specify a floating tag[^notimplemented]. -If you specify a specific upstream revision, then the downstream will not be changed unless the PackageVariant resource -itself is modified to point to a new revision. That is, the user must edit the PackageVariant, and change the upstream +If you specify a specific upstream revision, then the downstream will not be changed unless the *PackageVariant* resource +itself is modified to point to a new revision. That is, the user must edit the *PackageVariant*, and change the upstream package reference. When that is done, the package variant controller will update any existing Draft package under its ownership by doing the equivalent of a `kpt pkg update` to update the downstream to be based upon the new upstream revision. If a Draft does not exist, then the package variant controller will create a new Draft based on the current published downstream, and apply the `kpt pkg update`. This updated Draft must then be proposed and approved like any other package change. -If a floating tag is used, then explicit modification of the PackageVariant is not needed. Rather, when the floating tag +If a floating tag is used, then explicit modification of the *PackageVariant* is not needed. Rather, when the floating tag is moved to a new tagged revision of the upstream package, the package revision controller will notice and automatically propose and update to that revision. For example, the upstream package author may designate three floating tags: stable, -beta, and alpha. The upstream package author can move these tags to specific revisions, and any PackageVariant resource +beta, and alpha. The upstream package author can move these tags to specific revisions, and any *PackageVariant* resource tracking them will propose updates to their downstream packages. ### Adoption and Deletion Policies -When a PackageVariant resource is created, it will have a particular repository and package name as the downstream. The +When a *PackageVariant* resource is created, it will have a particular repository and package name as the downstream. The adoption policy controls whether the package variant controller takes over an existing package with that name, in that repository. -Analogously, when a PackageVariant resource is deleted, a decision must be made about whether or not to delete the +Analogously, when a *PackageVariant* resource is deleted, a decision must be made about whether or not to delete the downstream package. This is controlled by the deletion policy. ## Fan Out of Variant Generation[^pvsimpl] @@ -231,17 +231,17 @@ new versions of a package as the upstream changes, or as injected resources are automating common, systematic changes made when bringing an external package into an organization, or an organizational package into a team repository. -That is useful, but not extremely compelling by itself. More interesting is when we use PackageVariant as a primitive -for automations that act on other dimensions of scale. That means writing controllers that emit PackageVariant -resources. For example, we can create a controller that instantiates a PackageVariant for each developer in our -organization, or we can create a controller to manage PackageVariants across environments. The ability to not only clone +That is useful, but not extremely compelling by itself. More interesting is when we use *PackageVariant* as a primitive +for automations that act on other dimensions of scale. That means writing controllers that emit *PackageVariant* +resources. For example, we can create a controller that instantiates a *PackageVariant* for each developer in our +organization, or we can create a controller to manage *PackageVariant*s across environments. The ability to not only clone a package, but make systematic changes to that package enables flexible automation. Workload controllers in Kubernetes are a useful analogy. In Kubernetes, we have different workload controllers such as Deployment, StatefulSet, and DaemonSet. Ultimately, all of these result in Pods; however, the decisions about what Pods to create, how to schedule them across Nodes, how to configure those Pods, and how to manage those Pods as changes happen are very different with each workload controller. Similarly, we can build different controllers to handle -different ways in which we want to generate PackageRevisions. The PackageVariant resource provides a convenient +different ways in which we want to generate *PackageRevisions*. The *PackageVariant* resource provides a convenient primitive for all of those controllers, allowing a them to leverage a range of well-defined operations to mutate the packages as needed. @@ -250,12 +250,12 @@ include generating package variants to spin up development environments for each instantiating the same package, with slight configuration changes, across a fleet of clusters; or instantiating some package per customer. -The package variant set controller is designed to fill this common need. This controller consumes PackageVariantSet -resources, and outputs PackageVariant resources. The PackageVariantSet defines: +The package variant set controller is designed to fill this common need. This controller consumes *PackageVariantSet* +resources, and outputs *PackageVariant* resources. The *PackageVariantSet* defines: - the upstream package - targeting criteria -- a template for generating one PackageVariant per target +- a template for generating one *PackageVariant* per target Three types of targeting are supported: @@ -263,14 +263,14 @@ Three types of targeting are supported: - A label selector for Repository objects - An arbitrary object selector -Rules for generating a PackageVariant are associated with a list of targets using a template. That template can have -explicit values for various PackageVariant fields, or it can use +Rules for generating a *PackageVariant* are associated with a list of targets using a template. That template can have +explicit values for various *PackageVariant* fields, or it can use [Common Expression Language (CEL)](https://github.com/google/cel-go) expressions to specify the field values. -*Figure 5* shows an example of creating PackageVariant resources based upon the explicitly list of repositories. In this -example, for the `cluster-01` and `cluster-02` repositories, no template is defined the resulting PackageVariants; -it simply takes the defaults. However, for `cluster-03`, a template is defined to change the downstream package name to -`bar`. +*Figure 5* shows an example of creating *PackageVariant* resources based upon the explicitly list of repositories. In this +example, for the *cluster-01* and *cluster-02* repositories, no template is defined the resulting *PackageVariants*; +it simply takes the defaults. However, for *cluster-03*, a template is defined to change the downstream package name to +*bar*. | ![Figure 5: PackageVariantSet with Repository List](/static/images/porch/packagevariantset-target-list.png) | | :---: | @@ -278,16 +278,16 @@ it simply takes the defaults. However, for `cluster-03`, a template is defined t It is also possible to target the same package to a repository more than once, using different names. This is useful, for example, if the package is used to provision namespaces and you would like to provision many namespaces in the same -cluster. It is also useful if a repository is shared across multiple clusters. In *Figure 6*, two PackageVariant -resources for creating the `foo` package in the repository `cluster-01` are generated, one for each listed package name. -Since no `packageNames` field is listed for `cluster-02`, only one instance is created for that repository. +cluster. It is also useful if a repository is shared across multiple clusters. In *Figure 6*, two *PackageVariant* +resources for creating the *foo* package in the repository cluster-01 are generated, one for each listed package name. +Since no packageNames field is listed for cluster-02, only one instance is created for that repository. | ![Figure 6: PackageVariantSet with Package List](/static/images/porch/packagevariantset-target-list-with-packages.png) | | :---: | | *Figure 6: PackageVariantSet with Package List* | *Figure 7* shows an example that combines a repository label selector with configuration injection that various based -upon the target. The template for the PackageVariant includes a CEL expression for the one of the injectors, so that +upon the target. The template for the *PackageVariant* includes a CEL expression for the one of the injectors, so that the injection varies systematically based upon attributes of the target. | ![Figure 7: PackageVariantSet with Repository Selector](/static/images/porch/packagevariantset-target-repo-selector.png) | @@ -298,7 +298,7 @@ the injection varies systematically based upon attributes of the target. ### PackageVariant API -The Go types below defines the `PackageVariantSpec`. +The Go types below defines the PackageVariantSpec. ```go type PackageVariantSpec struct { @@ -343,74 +343,74 @@ type InjectionSelector struct { #### Basic Spec Fields -The `Upstream` and `Downstream` fields specify the source package and destination repository and package name. The -`Repo` fields refer to the names Porch Repository resources in the same namespace as the PackageVariant resource. -The `Downstream` does not contain a revision, because the package variant controller will only create Draft packages. -The `Revision` of the eventual PackageRevision resource will be determined by Porch at the time of approval. +The Upstream and Downstream fields specify the source package and destination repository and package name. The +Repo fields refer to the names Porch Repository resources in the same namespace as the *PackageVariant* resource. +The Downstream does not contain a revision, because the package variant controller will only create Draft packages. +The Revision of the eventual *PackageRevision* resource will be determined by Porch at the time of approval. -The `Labels` and `Annotations` fields list metadata to include on the created PackageRevision. These values are set -*only* at the time a Draft package is created. They are ignored for subsequent operations, even if the PackageVariant -itself has been modified. This means users are free to change these values on the PackageRevision; the package variant +The Labels and Annotations fields list metadata to include on the created *PackageRevision*. These values are set +*only* at the time a Draft package is created. They are ignored for subsequent operations, even if the *PackageVariant* +itself has been modified. This means users are free to change these values on the *PackageRevision*; the package variant controller will not touch them again. -`AdoptionPolicy` controls how the package variant controller behaves if it finds an existing PackageRevision Draft -matching the `Downstream`. If the `AdoptionPolicy` is `adoptExisting`, then the package variant controller will -take ownership of the Draft, associating it with this PackageVariant. This means that it will begin to reconcile the -Draft, just as if it had created it in the first place. An `AdoptionPolicy` of `adoptNone` (the default) will simply +AdoptionPolicy controls how the package variant controller behaves if it finds an existing *PackageRevision* Draft +matching the Downstream. If the AdoptionPolicy is adoptExisting, then the package variant controller will +take ownership of the Draft, associating it with this *PackageVariant*. This means that it will begin to reconcile the +Draft, just as if it had created it in the first place. An AdoptionPolicy of adoptNone (the default) will simply ignore any matching Drafts that were not created by the controller. -`DeletionPolicy` controls how the package variant controller behaves with respect to PackageRevisions that it has -created when the PackageVariant resource itself is deleted. A value of `delete` (the default) will delete the -PackageRevision (potentially removing it from a running cluster, if the downstream package has been deployed). A value -of `orphan` will remove the owner references and leave the PackageRevisions in place. +DeletionPolicy controls how the package variant controller behaves with respect to *PackageRevisions* that it has +created when the *PackageVariant* resource itself is deleted. A value of delete (the default) will delete the +*PackageRevision* (potentially removing it from a running cluster, if the downstream package has been deployed). A value +of orphan will remove the owner references and leave the *PackageRevisions* in place. #### Package Context Injection -PackageVariant resource authors may specify key-value pairs in the `spec.packageContext.data` field of the resource. -These key-value pairs will be automatically added to the `data` of the `kptfile.kpt.dev` ConfigMap, if it exists. +*PackageVariant* resource authors may specify key-value pairs in the spec.packageContext.data field of the resource. +These key-value pairs will be automatically added to the data of the *kptfile.kpt.dev* ConfigMap, if it exists. -Specifying the key `name` is invalid and must fail validation of the PackageVariant. This key is reserved for kpt or -Porch to set to the package name. Similarly, `package-path` is reserved and will result in an error. +Specifying the key name is invalid and must fail validation of the *PackageVariant*. This key is reserved for *kpt* or +Porch to set to the package name. Similarly, package-path is reserved and will result in an error. -The `spec.packageContext.removeKeys` field can also be used to specify a list of keys that the package variant -controller should remove from the `data` field of the `kptfile.kpt.dev` ConfigMap. +The spec.packageContext.removeKeys field can also be used to specify a list of keys that the package variant +controller should remove from the data field of the *kptfile.kpt.dev* ConfigMap. When creating or updating a package, the package variant controller will ensure that: -- The `kptfile.kpt.dev` ConfigMap exists, failing if not -- All of the key-value pairs in `spec.packageContext.data` exist in the `data` field of the ConfigMap. -- None of the keys listed in `spec.packageContext.removeKeys` exist in the ConfigMap. +- The *kptfile.kpt.dev* ConfigMap exists, failing if not +- All of the key-value pairs in spec.packageContext.data exist in the data field of the ConfigMap. +- None of the keys listed in spec.packageContext.removeKeys exist in the ConfigMap. {{% alert title="Note" color="primary" %}} -If a user adds a key via PackageVariant, then changes the PackageVariant to no longer add that key, it will -NOT be removed automatically, unless the user also lists the key in the `removeKeys` list. This avoids the need to track -which keys were added by PackageVariant. +If a user adds a key via *PackageVariant*, then changes the *PackageVariant* to no longer add that key, it will +NOT be removed automatically, unless the user also lists the key in the removeKeys list. This avoids the need to track +which keys were added by *PackageVariant*. {{% /alert %}} -Similarly, if a user manually adds a key in the downstream that is also listed in the `removeKeys` field, the package +Similarly, if a user manually adds a key in the downstream that is also listed in the removeKeys field, the package variant controller will remove that key the next time it needs to update the downstream package. There will be no attempt to coordinate "ownership" of these keys. If the controller is unable to modify the ConfigMap for some reason, this is considered an error and should prevent -generation of the Draft. This will result in the condition `Ready` being set to `False`. +generation of the Draft. This will result in the condition Ready being set to False. #### Kptfile Function Pipeline Editing -PackageVariant resource creators may specify a list of KRM functions to add to the beginning of the Kptfile's pipeline. -These functions are listed in the field `spec.pipeline`, which is a +*PackageVariant* resource creators may specify a list of KRM functions to add to the beginning of the *Kptfile's* pipeline. +These functions are listed in the field spec.pipeline, which is a [Pipeline](https://github.com/GoogleContainerTools/kpt/blob/cf1f326486214f6b4469d8432287a2fa705b48f5/pkg/api/kptfile/v1/types.go#L236), -just as in the Kptfile. The user can therefore prepend both `validators` and `mutators`. +just as in the *Kptfile*. The user can therefore prepend both validators and mutators. -Functions added in this way are always added to the *beginning* of the Kptfile pipeline. In order to enable management -of the list on subsequent reconciliations, functions added by the package variant controller will use the `Name` field +Functions added in this way are always added to the *beginning* of the *Kptfile* pipeline. In order to enable management +of the list on subsequent reconciliations, functions added by the package variant controller will use the Name field of the [Function](https://github.com/GoogleContainerTools/kpt/blob/cf1f326486214f6b4469d8432287a2fa705b48f5/pkg/api/kptfile/v1/types.go#L283). -In the Kptfile, each function will be named as the dot-delimited concatenation of `PackageVariant`, the name of the -PackageVariant resource, the function name as specified in the pipeline of the PackageVariant resource (if present), and +In the *Kptfile*, each function will be named as the dot-delimited concatenation of *PackageVariant*, the name of the +*PackageVariant* resource, the function name as specified in the pipeline of the *PackageVariant* resource (if present), and the positional location of the function in the array. -For example, if the PackageVariant resource contains: +For example, if the *PackageVariant* resource contains: ```yaml apiVersion: config.porch.kpt.dev/v1alpha1 @@ -431,7 +431,7 @@ spec: app: foo ``` -Then the resulting Kptfile will have these two entries prepended to its `mutators` list: +Then the resulting *Kptfile* will have these two entries prepended to its mutators list: ```yaml pipeline: @@ -447,30 +447,30 @@ Then the resulting Kptfile will have these two entries prepended to its `mutator ``` During subsequent reconciliations, this allows the controller to identify the functions within its control, remove them -all, and re-add them based on its updated content. By including the PackageVariant name, we enable chains of -PackageVariants to add functions, so long as the user is careful about their choice of resource names and avoids +all, and re-add them based on its updated content. By including the *PackageVariant* name, we enable chains of +*PackageVariants* to add functions, so long as the user is careful about their choice of resource names and avoids conflicts. If the controller is unable to modify the Pipeline for some reason, this is considered an error and should prevent -generation of the Draft. This will result in the condition `Ready` being set to `False`. +generation of the Draft. This will result in the condition Ready being set to False. #### Configuration Injection Details As described [above](#configuration-injection), configuration injection is a process whereby in-package resources are -matched to in-cluster resources, and the `spec` of the in-cluster resources is copied to the in-package resource. +matched to in-cluster resources, and the spec of the in-cluster resources is copied to the in-package resource. Configuration injection is controlled by a combination of in-package resources with annotations, and *injectors* -(also known as *injection selectors*) defined on the PackageVariant resource. Package authors control the injection +(also known as *injection selectors*) defined on the *PackageVariant* resource. Package authors control the injection points they allow in their packages, by flagging specific resources as *injection points* with an annotation. Creators -of the PackageVariant resource specify how to map in-cluster resources to those injection points using the injection -selectors. Injection selectors are defined in the `spec.injectors` field of the PackageVariant. This field is an ordered +of the *PackageVariant* resource specify how to map in-cluster resources to those injection points using the injection +selectors. Injection selectors are defined in the spec.injectors field of the *PackageVariant*. This field is an ordered array of structs containing a GVK (group, version, kind) tuple as separate fields, and name. Only the name is required. To identify a match, all fields present must match the in-cluster object, and all *GVK* fields present must match the in-package resource. In general the name will not match the in-package resource; this is discussed in more detail below. The annotations, along with the GVK of the annotated resource, allow a package to "advertise" the injections it can accept and understand. These injection points effectively form a configuration API for the package, and the injection -selectors provide a way for the PackageVariant author to specify the inputs for those APIs from the possible values in +selectors provide a way for the *PackageVariant* author to specify the inputs for those APIs from the possible values in the management cluster. If we define those APIs carefully, they can be used across many packages; since they are KRM resources, we can apply versioning and schema validation to them as well. This creates a more maintainable, automatable set of APIs for package customization than simple key/value pairs. @@ -479,78 +479,78 @@ As an example, we may define a GVK that contains service endpoints that many app package, we would then include an instance of that resource, say called "service-endpoints", and configure a function to propagate the values from that resource to others within our package. As those endpoints may vary by region, in our Porch cluster we can create an instance of this GVK for each region: "useast1-service-endpoints", -"useast2-service-endpoints", "uswest1-service-endpoints", etc. When we instantiate the PackageVariant for a cluster, we +"useast2-service-endpoints", "uswest1-service-endpoints", etc. When we instantiate the *PackageVariant* for a cluster, we want to inject the resource corresponding to the region in which the cluster exists. Thus, for each cluster we will -create a PackageVariant resource pointing to the upstream package, but with injection selector name values that are +create a *PackageVariant* resource pointing to the upstream package, but with injection selector name values that are specific to the region for that cluster. It is important to realize that the name of the in-package resource and the in-cluster resource need not match. In fact, -it would be an unusual coincidence if they did match. The names in the package are the same across PackageVariants -using that upstream, but we want to inject different resources for each one such PackageVariant. We also do not want to +it would be an unusual coincidence if they did match. The names in the package are the same across *PackageVariants* +using that upstream, but we want to inject different resources for each one such *PackageVariant*. We also do not want to change the name in the package, because it likely has meaning within the package and will be used by functions in the package. Also, different owners control the names of the in-package and in-cluster resources. The names in the package are in the control of the package author. The names in the cluster are in the control of whoever populates the cluster -(for example, some infrastructure team). The selector is the glue between them, and is in control of the PackageVariant +(for example, some infrastructure team). The selector is the glue between them, and is in control of the *PackageVariant* resource creator. The GVK on the other hand, has to be the same for the in-package resource and the in-cluster resource, because it tells us the API schema for the resource. Also, the namespace of the in-cluster object needs to be the same as the -PackageVariant resource, or we could leak resources from namespaces to which our PackageVariant user does not have +*PackageVariant* resource, or we could leak resources from namespaces to which our *PackageVariant* user does not have access. With that understanding, the injection process works as follows: 1. The controller will examine all in-package resources, looking for those with an annotation named - `kpt.dev/config-injection`, with one of the following values: `required` or `optional`. We will call these "injection + *kpt.dev/config-injection*, with one of the following values: required or optional. We will call these "injection points". It is the responsibility of the package author to define these injection points, and to specify which are required and which are optional. Optional injection points are a way of specifying default values. 1. For each injection point, a condition will be created *in the downstream PackageRevision*, with ConditionType set to - the dot-delimited concatenation of `config.injection`, with the in-package resource kind and name, and the value set - to `False`. Note that since the package author controls the name of the resource, kind and name are sufficient to + the dot-delimited concatenation of config.injection, with the in-package resource kind and name, and the value set + to False. Note that since the package author controls the name of the resource, kind and name are sufficient to disambiguate the injection point. We will call this ConditionType the injection point ConditionType". -1. For each required injection point, the injection point ConditionType will be added to the PackageRevision - `readinessGates` by the package variant controller. Optional injection points' ConditionTypes must not be added to - the `readinessGates` by the package variant controller, but humans or other actors may do so at a later date, and the +1. For each required injection point, the injection point ConditionType will be added to the *PackageRevision* + readinessGates by the package variant controller. Optional injection points' ConditionTypes must not be added to + the readinessGates by the package variant controller, but humans or other actors may do so at a later date, and the package variant controller should not remove them on subsequent reconciliations. Also, this relies upon - `readinessGates` gating publishing the package to a *deployment* repository, but not gating publishing to a blueprint + readinessGates gating publishing the package to a *deployment* repository, but not gating publishing to a blueprint repository. 1. The injection processing will proceed as follows. For each injection point: - - The controller will identify all in-cluster objects in the same namespace as the PackageVariant resource, with GVK + - The controller will identify all in-cluster objects in the same namespace as the *PackageVariant* resource, with GVK matching the injection point (the in-package resource). If the controller is unable to load this objects (e.g., - there are none and the CRD is not installed), the injection point ConditionType will be set to `False`, with a - message indicating that the error, and processing proceeds to the next injection point. Note that for `optional` + there are none and the CRD is not installed), the injection point ConditionType will be set to False, with a + message indicating that the error, and processing proceeds to the next injection point. Note that for optional injection this may be an acceptable outcome, so it does not interfere with overall generation of the Draft. - The controller will look through the list of injection selectors in order and checking if any of the in-cluster objects match the selector. If so, that in-cluster object is selected, and processing of the list of injection - selectors stops. Note that the namespace is set based upon the PackageVariant resource, the GVK is set based upon + selectors stops. Note that the namespace is set based upon the *PackageVariant* resource, the GVK is set based upon the in-package resource, and all selectors require name. Thus, at most one match is possible for any given selector. Also note that *all fields present in the selector* must match the in-cluster resource, and only the *GVK fields present in the selector* must match the in-package resource. - - If no in-cluster object is selected, the injection point ConditionType will be set to `False` with a message that + - If no in-cluster object is selected, the injection point ConditionType will be set to False with a message that no matching in-cluster resource was found, and processing proceeds to the next injection point. - If a matching in-cluster object is selected, then it is injected as follows: - - For ConfigMap resources, the `data` field from the in-cluster resource is copied to the `data` field of the + - For ConfigMap resources, the data field from the in-cluster resource is copied to the data field of the in-package resource (the injection point), overwriting it. - - For other resource types, the `spec` field from the in-cluster resource is copied to the `spec` field of the + - For other resource types, the spec field from the in-cluster resource is copied to the spec field of the in-package resource (the injection point), overwriting it. - - An annotation with name `kpt.dev/injected-resource-name` and value set to the name of the in-cluster resource is + - An annotation with name *kpt.dev/injected-resource-name* and value set to the name of the in-cluster resource is added (or overwritten) in the in-package resource. If the the overall injection cannot be completed for some reason, or if any of the below problems exist in the upstream package, it is considered an error and should prevent generation of the Draft: - There is a resource annotated as an injection point but having an invalid annotation value (i.e., other than - `required` or `optional`). + required or optional). - There are ambiguous condition types due to conflicting GVK and name values. These must be disambiguated in the upstream package, if so. -This will result in the condition `Ready` being set to `False`. +This will result in the condition Ready being set to False. {{% alert title="Note" color="primary" %}} -Whether or not all `required` injection points are fulfilled does not affect the *PackageVariant* conditions, +Whether or not all required injection points are fulfilled does not affect the *PackageVariant* conditions, only the *PackageRevision* conditions. {{% /alert %}} @@ -559,7 +559,7 @@ only the *PackageRevision* conditions. By allowing the use of GVK, not just name, in the selector, more precision in selection is enabled. This is a way to constrain the injections that will be done. That is, if the package has 10 different objects with -`config-injection` annotation, the PackageVariant could say it only wants to replace certain GVKs, allowing better +config-injection annotation, the *PackageVariant* could say it only wants to replace certain GVKs, allowing better control. Consider, for example, if the cluster contains these resources: @@ -569,8 +569,8 @@ Consider, for example, if the cluster contains these resources: - GVK2 foo - GVK2 bar -If we could only define injection selectors based upon name, it would be impossible to ever inject one GVK with `foo` -and another with `bar`. Instead, by using GVK, we can accomplish this with a list of selectors like: +If we could only define injection selectors based upon name, it would be impossible to ever inject one GVK with *foo* +and another with *bar*. Instead, by using GVK, we can accomplish this with a list of selectors like: - GVK1 foo - GVK2 bar @@ -583,50 +583,50 @@ different GVKs. During creation, the first thing the controller does is clone the upstream package to create the downstream package. -For update, first note that changes to the downstream PackageRevision can be triggered for several different reasons: +For update, first note that changes to the downstream *PackageRevision* can be triggered for several different reasons: -1. The PackageVariant resource is updated, which could change any of the options for introducing variance, or could also +1. The *PackageVariant* resource is updated, which could change any of the options for introducing variance, or could also change the upstream package revision referenced. 1. A new revision of the upstream package has been selected due to a floating tag change, or due to a force retagging of the upstream. 1. An injected in-cluster object is updated. -The downstream PackageRevision may have been updated by humans or other automation actors since creation, so we cannot -simply recreate the downstream PackageRevision from scratch when one of these changes happens. Instead, the controller +The downstream *PackageRevision* may have been updated by humans or other automation actors since creation, so we cannot +simply recreate the downstream *PackageRevision* from scratch when one of these changes happens. Instead, the controller must maintain the later edits by doing the equivalent of a `kpt pkg update`, in the case of changes to the upstream for -any reason. Any other changes require reapplication of the PackageVariant functionality. With that understanding, we can +any reason. Any other changes require reapplication of the *PackageVariant* functionality. With that understanding, we can see that the controller will perform mutations on the downstream package in this order, for both creation and update: 1. Create (via Clone) or Update (via `kpt pkg update` equivalent) - This is done by the Porch server, not by the package variant controller directly. - - This means that Porch will run the Kptfile pipeline after clone or update. + - This means that Porch will run the *Kptfile* pipeline after clone or update. 1. Package variant controller applies configured mutations - Package Context Injections - - Kptfile KRM Function Pipeline Additions/Changes + - *Kptfile* KRM Function Pipeline Additions/Changes - Config Injection -1. Package variant controller saves the PackageRevision and PackageRevisionResources. +1. Package variant controller saves the *PackageRevision* and *PackageRevisionResources*. - - Porch server executes the Kptfile pipeline + - Porch server executes the *Kptfile* pipeline -The package variant controller mutations edit resources (including the Kptfile), based on the contents of the -PackageVariant and the injected in-cluster resources, but cannot affect one another. The results of those mutations -throughout the rest of the package is materialized by the execution of the Kptfile pipeline during the save operation. +The package variant controller mutations edit resources (including the *Kptfile*), based on the contents of the +*PackageVariant* and the injected in-cluster resources, but cannot affect one another. The results of those mutations +throughout the rest of the package is materialized by the execution of the *Kptfile* pipeline during the save operation. #### PackageVariant Status PackageVariant sets the following status conditions: - - `Stalled` is set to True if there has been a failure that most likely requires user intervention. - - `Ready` is set to True if the last reconciliation successfully produced an up-to-date Draft. + - **Stalled** is set to True if there has been a failure that most likely requires user intervention. + - **Ready** is set to True if the last reconciliation successfully produced an up-to-date Draft. -The PackageVariant resource will also contain a `DownstreamTargets` field, containing a list of downstream `Draft` and -`Proposed` PackageRevisions owned by this PackageVariant resource, or the latest `Published` PackageRevision if there -are none in `Draft` or `Proposed` state. Typically, there is only a single Draft, but use of the `adopt` value for -`AdoptionPolicy` could result in multiple Drafts being owned by the same PackageVariant. +The *PackageVariant* resource will also contain a DownstreamTargets field, containing a list of downstream Draft and +Proposed *PackageRevisions* owned by this *PackageVariant* resource, or the latest Published *PackageRevision* if there +are none in Draft or Proposed state. Typically, there is only a single Draft, but use of the adopt value for +AdoptionPolicy could result in multiple Drafts being owned by the same *PackageVariant*. ### PackageVariantSet API[^pvsimpl] @@ -656,19 +656,19 @@ type Target struct { } ``` -At the highest level, a PackageVariantSet is just an upstream, and a list of targets. For each target, there is a set of -criteria for generating a list, and a set of rules (a template) for creating a PackageVariant from each list entry. +At the highest level, a *PackageVariantSet* is just an upstream, and a list of targets. For each target, there is a set of +criteria for generating a list, and a set of rules (a template) for creating a *PackageVariant* from each list entry. -Since `template` is optional, lets start with describing the different types of targets, and how the criteria in each is -used to generate a list that seeds the PackageVariant resources. +Since template is optional, lets start with describing the different types of targets, and how the criteria in each is +used to generate a list that seeds the *PackageVariant* resources. -The `Target` structure must include exactly one of three different ways of generating the list. The first is a simple +The Target structure must include exactly one of three different ways of generating the list. The first is a simple list of repositories and package names for each of those repositories[^repo-pkg-expr]. The package name list is needed for uses cases in which you want to repeatedly instantiate the same package in a single repository. For example, if a repository represents the contents of a cluster, you may want to instantiate a namespace package once for each namespace, with a name matching the namespace. -This example shows using the `repositories` field: +This example shows using the repositories field: ```yaml apiVersion: config.porch.kpt.dev/v1alpha2 @@ -696,7 +696,7 @@ spec: - foo-b ``` -In this case, PackageVariant resources are created for each of these pairs of downstream repositories and packages +In this case, *PackageVariant* resources are created for each of these pairs of downstream repositories and packages names: | Repository | Package Name | @@ -709,7 +709,7 @@ names: | cluster-04 | foo-a | | cluster-04 | foo-b | -All of those PackageVariants have the same upstream. +All of those *PackageVariants* have the same upstream. The second criteria targeting is via a label selector against Porch Repository objects, along with a list of package names. Those packages will be instantiated in each matching repository. Just like in the first example, not listing a @@ -723,7 +723,7 @@ four repositories defined in our Porch cluster: | cluster-03 | region=useast2, env=prod, org=hr | | cluster-04 | region=uswest1, env=prod, org=hr | -If we create a PackageVariantSet with the following `spec`: +If we create a *PackageVariantSet* with the following spec: ```yaml spec: @@ -745,7 +745,7 @@ spec: - foo-c ``` -then PackageVariant resources will be created with these repository and package names: +then *PackageVariant* resources will be created with these repository and package names: | Repository | Package Name | | ---------- | ------------ | @@ -760,7 +760,7 @@ then PackageVariant resources will be created with these repository and package | cluster-04 | foo-c | Finally, the third possibility allows the use of *arbitrary* resources in the Porch cluster as targeting criteria. The -`objectSelector` looks like this: +objectSelector looks like this: ```yaml spec: @@ -778,16 +778,16 @@ spec: ``` It works exactly like the repository selector - in fact the repository selector is equivalent to the object selector -with the `apiVersion` and `kind` values set to point to Porch Repository resources. That is, the repository name comes +with the apiVersion and kind values set to point to Porch Repository resources. That is, the repository name comes from the object name, and the package names come from the listed package names. In the description of the template, we will see how to derive different repository names from the objects. #### PackageVariant Template -As previously discussed, the list entries generated by the target criteria result in PackageVariant entries. If no -template is specified, then PackageVariant default are used, along with the downstream repository name and package name +As previously discussed, the list entries generated by the target criteria result in *PackageVariant* entries. If no +template is specified, then *PackageVariant* default are used, along with the downstream repository name and package name as described in the previous section. The template allows the user to have control over all of the values in the -resulting PackageVariant. The template API is shown below. +resulting *PackageVariant*. The template API is shown below. ```go type PackageVariantTemplate struct { @@ -906,11 +906,11 @@ type FunctionTemplate struct { ``` This is a pretty complicated structure. To make it more understandable, the first thing to notice is that many fields -have a plain version, and an `Expr` version. The plain version is used when the value is static across all the -PackageVariants; the `Expr` version is used when the value needs to vary across PackageVariants. +have a plain version, and an Expr version. The plain version is used when the value is static across all the +*PackageVariants*; the Expr version is used when the value needs to vary across *PackageVariants*. Let's consider a simple example. Suppose we have a package for provisioning namespaces called "base-ns". We want to -instantiate this several times in the `cluster-01` repository. We could do this with this PackageVariantSet: +instantiate this several times in the *cluster-01* repository. We could do this with this *PackageVariantSet*: ```yaml apiVersion: config.porch.kpt.dev/v1alpha2 @@ -932,9 +932,9 @@ spec: - ns-3 ``` -That will produce three PackageVariant resources with the same upstream, all with the same downstream repo, and each +That will produce three *PackageVariant* resources with the same upstream, all with the same downstream repo, and each with a different downstream package name. If we also want to set some labels identically across the packages, we can -do that with the `template.labels` field: +do that with the template.labels field: ```yaml apiVersion: config.porch.kpt.dev/v1alpha2 @@ -960,8 +960,8 @@ spec: org: hr ``` -The resulting PackageVariant resources will include `labels` in their `spec`, and will be identical other than their -names and the `downstream.package`: +The resulting *PackageVariant* resources will include labels in their spec, and will be identical other than their +names and the downstream.package: ```yaml apiVersion: config.porch.kpt.dev/v1alpha1 @@ -1017,10 +1017,10 @@ spec: org: hr ``` -When using other targeting means, the use of the `Expr` fields becomes more likely, because we have more possible -sources for different field values. The `Expr` values are all +When using other targeting means, the use of the Expr fields becomes more likely, because we have more possible +sources for different field values. The Expr values are all [Common Expression Language (CEL)](https://github.com/google/cel-go) expressions, rather than static values. This allows -the user to construct values based upon various fields of the targets. Consider again the `repositorySelector` example, +the user to construct values based upon various fields of the targets. Consider again the repositorySelector example, where we have these repositories in the cluster. | Repository | Labels | @@ -1030,10 +1030,10 @@ where we have these repositories in the cluster. | cluster-03 | region=useast2, env=prod, org=hr | | cluster-04 | region=uswest1, env=prod, org=hr | -If we create a PackageVariantSet with the following `spec`, we can use the `Expr` fields to add labels to the -PackageVariantSpecs (and thus to the resulting PackageRevisions later) that vary based on cluster. We can also use -this to vary the `injectors` defined for each PackageVariant, resulting in each PackageRevision having different -resources injected. This `spec`: +If we create a *PackageVariantSet* with the following spec, we can use the Expr fields to add labels to the +*PackageVariantSpecs* (and thus to the resulting *PackageRevisions* later) that vary based on cluster. We can also use +this to vary the injectors defined for each *PackageVariant*, resulting in each *PackageRevision* having different +resources injected. This spec: ```yaml spec: @@ -1054,9 +1054,9 @@ spec: - nameExpr: "repository.labels['region'] + '-endpoints'" ``` -will result in three PackageVariant resources, one for each Repository with the labels env=prod and org=hr. The `labels` -and `injectors` fields of the PackageVariantSpec will be different for each of these PackageVariants, as determined by -the use of the `Expr` fields in the template, as shown here: +will result in three *PackageVariant* resources, one for each Repository with the labels env=prod and org=hr. The labels +and injectors fields of the *PackageVariantSpec* will be different for each of these *PackageVariants*, as determined by +the use of the Expr fields in the template, as shown here: ```yaml apiVersion: config.porch.kpt.dev/v1alpha1 @@ -1114,65 +1114,65 @@ spec: name: uswest1-endpoints ``` -Since the injectors are different for each PackageVariant, the resulting PackageRevisions will each have different +Since the injectors are different for each *PackageVariant*, the resulting *PackageRevisions* will each have different resources injected. When CEL expressions are evaluated, they have an environment associated with them. That is, there are certain objects -that are accessible within the CEL expression. For CEL expressions used in the PackageVariantSet `template` field, +that are accessible within the CEL expression. For CEL expressions used in the *PackageVariantSet* template field, the following variables are available: | CEL Variable | Variable Contents | | -------------- | ------------------------------------------------------------ | | repoDefault | The default repository name based on the targeting criteria. | | packageDefault | The default package name based on the targeting criteria. | -| upstream | The upstream PackageRevision. | +| upstream | The upstream *PackageRevision*. | | repository | The downstream Repository. | | target | The target object (details vary; see below). | -There is one expression that is an exception to the table above. Since the `repository` value corresponds to the -Repository of the downstream, we must first evaluate the `downstream.repoExpr` expression to *find* that repository. -Thus, for that expression only, `repository` is not a valid variable. +There is one expression that is an exception to the table above. Since the repository value corresponds to the +Repository of the downstream, we must first evaluate the downstream.repoExpr expression to find that repository. +Thus, for that expression only, repository is not a valid variable. -There is one more variable available across all CEL expressions: the `target` variable. This variable has a meaning that +There is one more variable available across all CEL expressions: the target variable. This variable has a meaning that varies depending on the type of target, as follows: -| Target Type | `target` Variable Contents | +| Target Type | target Variable Contents | | ------------------- | ---------------------------------------------------------------------------------------------- | -| Repo/Package List | A struct with two fields: `repo` and `package`, the same as the `repoDefault` and `packageDefault` values. | -| Repository Selector | The Repository selected by the selector. Although not recommended, this could be different than the `repository` value, which an be altered with `downstream.repo` or `downstream.repoExpr`. | +| Repo/Package List | A struct with two fields: repo and package, the same as the repoDefault and packageDefault values. | +| Repository Selector | The Repository selected by the selector. Although not recommended, this could be different than the repository value, which an be altered with downstream.repo or downstream.repoExpr. | | Object Selector | The Object selected by the selector. | -For the various resource variables - `upstream`, `repository`, and `target` - arbitrary access to all fields of the +For the various resource variables - upstream, repository, and target - arbitrary access to all fields of the object could lead to security concerns. Therefore, only a subset of the data is available for use in CEL expressions. -Specifically, the following fields: `name`, `namespace`, `labels`, and `annotations`. +Specifically, the following fields: name, namespace, labels, and annotations. -Given the slight quirk with the `repoExpr`, it may be helpful to state the processing flow for the template evaluation: +Given the slight quirk with the repoExpr, it may be helpful to state the processing flow for the template evaluation: -1. The upstream PackageRevision is loaded. It must be in the same namespace as the PackageVariantSet[^multi-ns-reg]. +1. The upstream *PackageRevision* is loaded. It must be in the same namespace as the *PackageVariantSet*[^multi-ns-reg]. 1. The targets are determined. 1. For each target: - 1. The CEL environment is prepared with `repoDefault`, `packageDefault`, `upstream`, and `target` variables. + 1. The CEL environment is prepared with repoDefault, packageDefault, upstream, and target variables. 1. The downstream repository is determined and loaded, as follows: - - If present, `downstream.repoExpr` is evaluated using the CEL environment, and the result used as the downstream + - If present, downstream.repoExpr is evaluated using the CEL environment, and the result used as the downstream repository name. - - Otherwise, if `downstream.repo` is set, that is used as the downstream repository name. + - Otherwise, if downstream.repo is set, that is used as the downstream repository name. - If neither is present, the default repository name based on the target is used (i.e., the same value as the - `repoDefault` variable). + repoDefault variable). - The resulting downstream repository name is used to load the corresponding Repository object in the same - namespace as the PackageVariantSet. + namespace as the *PackageVariantSet*. 1. The downstream Repository is added to the CEL environment. 1. All other CEL expressions are evaluated. -1. Note that if any of the resources (e.g., the upstream PackageRevision, or the downstream Repository) are not found +1. Note that if any of the resources (e.g., the upstream *PackageRevision*, or the downstream Repository) are not found our otherwise fail to load, processing stops and a failure condition is raised. Similarly, if a CEL expression cannot be properly evaluated due to syntax or other reasons, processing stops and a failure condition is raised. #### Other Considerations -It would appear convenient to automatically inject the PackageVariantSet targeting resource. However, it is better to +It would appear convenient to automatically inject the *PackageVariantSet* targeting resource. However, it is better to require the package advertise the ways it accepts injections (i.e., the GVKs it understands), and only inject those. This keeps the separation of concerns cleaner; the package does not build in an awareness of the context in which it expects to be deployed. For example, a package should not accept a Porch Repository resource just because that happens @@ -1180,37 +1180,37 @@ to be the targeting mechanism. That would make the package unusable in other con #### PackageVariantSet Status -The PackageVariantSet status uses these conditions: +The *PackageVariantSet* status uses these conditions: - - `Stalled` is set to True if there has been a failure that most likely requires user intervention. - - `Ready` is set to True if the last reconciliation successfully reconciled all targeted PackageVariant resources. + - Stalled is set to True if there has been a failure that most likely requires user intervention. + - Ready is set to True if the last reconciliation successfully reconciled all targeted *PackageVariant* resources. ## Future Considerations - As an alternative to the floating tag proposal, we may instead want to have a separate tag tracking controller that can update PV and PVS resources to tweak their upstream as the tag moves. - Installing a collection of packages across a set of clusters, or performing the same mutations to each package in a - collection, is only supported by creating multiple PackageVariant / PackageVariantSet resources. Options to consider + collection, is only supported by creating multiple *PackageVariant* / *PackageVariantSet* resources. Options to consider for these use cases: - - `upstreams` listing multiple packages. - - Label selector against PackageRevisions. This does not seem that useful, as PackageRevisions are highly re-usable + - upstreams listing multiple packages. + - Label selector against *PackageRevisions*. This does not seem that useful, as *PackageRevisions* are highly re-usable and would likely be composed in many different ways. - - A PackageRevisionSet resource that simply contained a list of Upstream structures and could be used as an Upstream. - This is functionally equivalent to the `upstreams` option, but that list is reusable across resources. - - Listing multiple PackageRevisionSets in the upstream would be nice as well. - - Any or all of these could be implemented in PackageVariant, PackageVariantSet, or both. + - A *PackageRevisionSet* resource that simply contained a list of Upstream structures and could be used as an Upstream. + This is functionally equivalent to the upstreams option, but that list is reusable across resources. + - Listing multiple *PackageRevisionSets* in the upstream would be nice as well. + - Any or all of these could be implemented in *PackageVariant*, *PackageVariantSet*, or both. ## Footnotes [^porch17]: Implemented in Porch v0.0.17. [^porch18]: Coming in Porch v0.0.18. [^notimplemented]: Proposed here but not yet implemented as of Porch v0.0.18. -[^setns]: As of this writing, the `set-namespace` function does not have a `create` option. This should be added to +[^setns]: As of this writing, the set-namespace function does not have a create option. This should be added to avoid the user needing to also usethe `upsert-resource` function. Such common operation should be simple forusers. -[^pvsimpl]: This document describes PackageVariantSet `v1alpha2`, which will be available starting with Porch v0.0.18. - In Porch v0.0.16 and 17, the `v1alpha1` implementation is available, but it is a somewhat different API, without +[^pvsimpl]: This document describes *PackageVariantSet* v1alpha2, which will be available starting with Porch v0.0.18. + In Porch v0.0.16 and 17, the v1alpha1 implementation is available, but it is a somewhat different API, without support for CEL or any injection. It is focused only on fan out targeting, and uses a [slightly different targeting API](https://github.com/nephio-project/porch/blob/main/controllers/packagevariants/api/v1alpha1/packagevariant_types.go). -[^repo-pkg-expr]: This is not exactly correct. As we will see later in the `template` discussion, this the repository +[^repo-pkg-expr]: This is not exactly correct. As we will see later in the template discussion, this the repository and package names listed actually are just defaults for the template; they can be further manipulated in the template to reference different downstream repositories and package names. The same is true for the repositories selected via the `repositorySelector` option. However, this can be ignored for now. diff --git a/content/en/docs/porch/running-porch/running-locally.md b/content/en/docs/porch/running-porch/running-locally.md index 779c39a4..0a2ec8f9 100644 --- a/content/en/docs/porch/running-porch/running-locally.md +++ b/content/en/docs/porch/running-porch/running-locally.md @@ -20,7 +20,7 @@ To run Porch locally, you will need: ## Getting Started -Clone this repository into `${GOPATH}/src/github.com/GoogleContainerTools/kpt`. +Clone this repository into *${GOPATH}/src/github.com/GoogleContainerTools/kpt*. ```sh git clone https://github.com/GoogleContainerTools/kpt.git "${GOPATH}/src/github.com/GoogleContainerTools/kpt" @@ -53,8 +53,8 @@ make This will: -* create Docker network named `porch` -* build and start `etcd` Docker container +* create Docker network named *porch* +* build and start etcd Docker container * build and start main k8s apiserver Docker container * build and start the kpt function evaluator microservice [func](https://github.com/nephio-project/porch/tree/main/func) Docker container @@ -121,5 +121,5 @@ make stop ## Troubleshooting -If you run into issues that look like `git: authentication required`, make sure you have SSH +If you run into issues that look like *git: authentication required*, make sure you have SSH keys set up on your local machine. diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index 0c19468b..1d0cc5f7 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -25,7 +25,7 @@ need: * [gcloud](https://cloud.google.com/sdk/docs/install) * [kubectl](https://kubernetes.io/docs/tasks/tools/); you can install it via `gcloud components install kubectl` * [kpt](https://kpt.dev/) -* Command line utilities such as `curl`, `tar` +* Command line utilities such as *curl*, *tar* To build and run Porch on GKE, you will also need: @@ -40,8 +40,8 @@ To build and run Porch on GKE, you will also need: ## Getting Started -Make sure your `gcloud` is configured with your project (alternatively, you can augment all following `gcloud` -commands below with `--project` flag): +Make sure your gcloud is configured with your project (alternatively, you can augment all following gcloud +commands below with --project flag): ```bash gcloud config set project YOUR_GCP_PROJECT @@ -63,7 +63,7 @@ gcloud services enable container.googleapis.com gcloud container clusters create --region us-central1 porch-dev ``` -And ensure `kubectl` is targeting your GKE cluster: +And ensure *kubectl* is targeting your GKE cluster: ```bash gcloud container clusters get-credentials --region us-central1 porch-dev @@ -75,7 +75,7 @@ gcloud container clusters get-credentials --region us-central1 porch-dev To run a released version of Porch, download the release config bundle from [Porch release page](https://github.com/nephio-project/porch/releases). -Untar and apply the `deployment-blueprint.tar.gz` config bundle. This will install: +Untar and apply the *deployment-blueprint.tar.gz* config bundle. This will install: * Porch server * [Config Sync](https://kpt.dev/gitops/configsync/) @@ -87,7 +87,7 @@ kubectl apply -f porch-install kubectl wait deployment --for=condition=Available porch-server -n porch-system ``` -You can verify that Porch is running by querying the `api-resources`: +You can verify that Porch is running by querying the api-resources: ```bash kubectl api-resources | grep porch @@ -119,7 +119,7 @@ spec: To run custom build of Porch, you will need additional [prerequisites](#prerequisites). The commands below use [Google Container Registry](https://console.cloud.google.com/gcr). -Clone this repository into `${GOPATH}/src/github.com/GoogleContainerTools/kpt`. +Clone this repository into *${GOPATH}/src/github.com/GoogleContainerTools/kpt*. ```bash git clone https://github.com/GoogleContainerTools/kpt.git "${GOPATH}/src/github.com/GoogleContainerTools/kpt" @@ -136,7 +136,7 @@ named (example shown is the Porch server image). IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa ``` -If you want to use a different repository, you can set `IMAGE_REPO` variable +If you want to use a different repository, you can set IMAGE_REPO variable (see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L32) for details). The `make push-and-deploy-no-sa` target will install Porch but not Config Sync. You can install Config Sync in your k8s @@ -145,12 +145,12 @@ cluster manually following the {{% alert title="Note" color="primary" %}} -The `-no-sa` (no service account) targets create Porch deployment +The -no-sa (no service account) targets create Porch deployment configuration which does not associate Kubernetes service accounts with GCP service accounts. This is sufficient for Porch to integate with Git repositories using Basic Auth, for example GitHub. -As above, you can verify that Porch is running by querying the `api-resources`: +As above, you can verify that Porch is running by querying the api-resources: ```bash kubectl api-resources | grep porch @@ -191,14 +191,14 @@ kubectl annotate serviceaccount porch-server -n porch-system \ iam.gke.io/gcp-service-account=porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com ``` -Build Porch, push images, and deploy porch server and controllers using the `make` target that adds workload identity +Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity service account annotations: ```bash IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy ``` -As above, you can verify that Porch is running by querying the `api-resources`: +As above, you can verify that Porch is running by querying the api-resources: ```bash kubectl api-resources | grep porch @@ -246,14 +246,14 @@ gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}. --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]" ``` -Build Porch, push images, and deploy porch server and controllers using the `make` target that adds workload identity +Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity service account annotations: ```bash IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy ``` -As above, you can verify that Porch is running by querying the `api-resources`: +As above, you can verify that Porch is running by querying the api-resources: ```bash kubectl api-resources | grep porch diff --git a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md b/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md index 8b20a5f4..b24fd92a 100644 --- a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md +++ b/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md @@ -11,15 +11,13 @@ To enable the porch server to communicate with a custom git deployment over HTTP The secret itself must meet the following criteria: -- exist in the same `namespace` as the Repository CR (Custom Resource) that requires it -- be named specifically `-ca-bundle` -- have a Data key named `ca.crt` containing the relevant ca certificate (chain) +- exist in the same namespace as the Repository CR (Custom Resource) that requires it +- be named specifically \-ca-bundle +- have a Data key named *ca.crt* containing the relevant ca certificate (chain) -For example, a Git Repository is hosted over HTTPS at the following URL: +For example, a Git Repository is hosted over HTTPS at the *https://my-gitlab.com/joe.bloggs/blueprints.git* URL: -`https://my-gitlab.com/joe.bloggs/blueprints.git` - -Before creating the new Repository in the **gitlab** namespace, we must create a secret that fulfils the criteria above. +Before creating the new Repository in the *gitlab* namespace, we must create a secret that fulfils the criteria above. `kubectl create secret generic gitlab-ca-bundle --namespace=gitlab --from-file=ca.crt` diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index 3c96742f..cbf988c1 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -7,7 +7,7 @@ description: "A tutorial to install and use Porch" This tutorial is a guide to installing and using Porch. It is based on the [Porch demo produced by Tal Liron of Google](https://github.com/tliron/klab/tree/main/environments/porch-demo). Users -should be very comfortable with using `git`, `docker`, and `kubernetes`. +should be very comfortable with using *git*, *docker*, and *kubernetes*. See also [the Nephio Learning Resource](https://github.com/nephio-project/docs/blob/main/learning.md) page for background help and information. @@ -45,14 +45,14 @@ kind create cluster --config=kind_management_cluster.yaml kind create cluster --config=kind_edge1_cluster.yaml ``` -Output the kubectl config for the clusters: +Output the *kubectl* config for the clusters: ```bash kind get kubeconfig --name=management > ~/.kube/kind-management-config kind get kubeconfig --name=edge1 > ~/.kube/kind-edge1-config ``` -Toggling kubectl between the clusters: +Toggling *kubectl* between the clusters: ```bash export KUBECONFIG=~/.kube/kind-management-config @@ -73,7 +73,7 @@ kubectl wait --namespace metallb-system \ --timeout=90s ``` -Check the subnet that is being used by the `kind` network in docker +Check the subnet that is being used by the kind network in docker ```bash docker network inspect kind | grep Subnet @@ -86,7 +86,7 @@ Sample output: "Subnet": "fc00:f853:ccd:e793::/64" ``` -Edit the `metallb-conf.yaml` file and ensure the `spec.addresses` range is in the IPv4 subnet being used by the `kind` network in docker. +Edit the *metallb-conf.yaml* file and ensure the spec.addresses range is in the IPv4 subnet being used by the kind network in docker. ```yaml ... @@ -104,7 +104,7 @@ kubectl apply -f metallb-conf.yaml ## Deploy and set up gitea on the management cluster using kpt -Get the gitea kpt package: +Get the *gitea kpt* package: ```bash export KUBECONFIG=~/.kube/kind-management-config @@ -114,7 +114,7 @@ cd kpt_packages kpt pkg get https://github.com/nephio-project/catalog/tree/main/distros/sandbox/gitea ``` -Comment out the preconfigured IP address from the `gitea/service-gitea.yaml` file in the gitea Kpt package: +Comment out the preconfigured IP address from the *gitea/service-gitea.yaml* file in the *gitea kpt* package: ```bash 11c11 @@ -123,7 +123,7 @@ Comment out the preconfigured IP address from the `gitea/service-gitea.yaml` fil > # metallb.universe.tf/loadBalancerIPs: 172.18.0.200 ``` -Now render, init and apply the Gitea Kpt package: +Now render, init and apply the *gitea kpt* package: ```bash kpt fn render gitea @@ -142,11 +142,11 @@ gitea LoadBalancer 10.96.243.120 172.18.255.200 22:31305/TCP,3000:31102/ The UI is available at http://172.18.255.200:3000 in the example above. -To login to Gitea, use the credentials `nephio:secret`. +To login to Gitea, use the credentials nephio:secret. ## Create repositories on Gitea for management and edge1 -On the gitea UI, click the '+' opposite "Repositories" and fill in the form for both the `management` and `edge1` repositories. Use default values except for the following fields: +On the gitea UI, click the **+** opposite **Repositories** and fill in the form for both the *management* and *edge1* repositories. Use default values except for the following fields: - Repository Name: "Management" or "edge1" - Description: Something appropriate @@ -167,7 +167,7 @@ Check the repos: Now initialize both repos with an initial commit. -Initialize the `management` repo +Initialize the *management* repo ```bash cd ../repos @@ -188,7 +188,7 @@ git push -u origin main cd .. ``` -Initialize the `edge1` repo +Initialize the *edge1* repo ```bash git clone http://172.18.255.200:3000/nephio/edge1 @@ -210,7 +210,7 @@ cd ../../ ## Install Porch -We will use the Porch Kpt package from Nephio catalog repo. +We will use the *Porch Kpt* package from Nephio catalog repo. ```bash cd kpt_packages @@ -218,7 +218,7 @@ cd kpt_packages kpt pkg get https://github.com/nephio-project/catalog/tree/main/nephio/core/porch ``` -Now we can install porch. We render the kpt package and then init and apply it. +Now we can install porch. We render the *kpt* package and then init and apply it. ```bash kpt fn render porch @@ -287,7 +287,7 @@ management git Package false True http://172.18.255.20 ## Configure configsync on the workload cluster -Configsync is installed on the `edge1` cluster so that it syncs the contents of the `edge1` repository onto the `edge1` +Configsync is installed on the edge1 cluster so that it syncs the contents of the *edge1* repository onto the edge1 workload cluster. We will use the configsync package from Nephio. ```bash @@ -310,13 +310,13 @@ config-management-operator-6946b77565-f45pc 1/1 Running 0 118m reconciler-manager-5b5d8557-gnhb2 2/2 Running 0 118m ``` -Now, we need to set up a Rootsync CR to synchronize the `edge1` repo: +Now, we need to set up a Rootsync CR to synchronize the *edge1* repo: ```bash kpt pkg get https://github.com/nephio-project/catalog/tree/main/nephio/optional/rootsync ``` -Edit the `rootsync/package-context.yaml` file to set the name of the cluster/repo we are syncing from/to: +Edit the *rootsync/package-context.yaml* file to set the name of the cluster/repo we are syncing from/to: ```bash 9c9 @@ -325,13 +325,13 @@ Edit the `rootsync/package-context.yaml` file to set the name of the cluster/rep > name: edge1 ``` -Render the package. This configures the `rootsync/rootsync.yaml` file in the Kpt package: +Render the package. This configures the *rootsync/rootsync.yaml* file in the Kpt package: ```bash kpt fn render rootsync ``` -Edit the `rootsync/rootsync.yaml` file to set the IP address of Gitea and to turn off authentication for accessing +Edit the *rootsync/rootsync.yaml* file to set the IP address of Gitea and to turn off authentication for accessing gitea: ```bash @@ -437,7 +437,7 @@ external-blueprints git Package false True https://github.com/n management git Package false True http://172.18.255.200:3000/nephio/management.git ``` -A repository is a CR of the Porch Repository CRD. You can examine the 'repositories.config.porch.kpt.dev' CRD with +A repository is a CR of the Porch Repository CRD. You can examine the *repositories.config.porch.kpt.dev* CRD with either of the following commands (both of which are rather verbose): ```bash @@ -529,9 +529,9 @@ external-blueprints-60ef45bb8f55b63556e7467f16088325022a7ece pkg-example-upf-b external-blueprints-7757966cc7b965f1b9372370a4b382c8375a2b40 pkg-example-upf-bp v5 v5 external-blueprints 17 ``` -Let's examine the `free5gc-cp v1` package. +Let's examine the *free5gc-cp v1* package. -The PackageRevision CR name for free5gc-cp v1 is external-blueprints-dabbc422fdf0b8e5942e767d929b524e25f7eef9. +The PackageRevision CR name for *free5gc-cp v1* is external-blueprints-dabbc422fdf0b8e5942e767d929b524e25f7eef9. ```bash kubectl get packagerevision -n porch-demo external-blueprints-dabbc422fdf0b8e5942e767d929b524e25f7eef9 -o yaml @@ -560,7 +560,7 @@ status: upstreamLock: {} ``` -Getting the PackageRevisionResources pulls the package from its repository with each file serialized into a name-value +Getting the *PackageRevisionResources* pulls the package from its repository with each file serialized into a name-value map of resources in it's spec.
@@ -1310,7 +1310,7 @@ management git Package false True http://172.18.255.20 ```
-Check that porchctl lists our remote packages (PackageRevisions): +Check that porchctl lists our remote packages (PackageRevisions): ``` porchctl rpkg -n porch-demo get @@ -1352,7 +1352,7 @@ The output above is similar to the output of `kubectl get packagerevision -n por ### Blueprint with no Kpt pipelines -Create a new package in our `management` repo using the sample `network-function` package provided. This network function kpt package is a demo Kpt package that installs [nginx](https://github.com/nginx). +Create a new package in our *management* repo using the sample *network-function* package provided. This network function kpt package is a demo Kpt package that installs [nginx](https://github.com/nginx). ``` porchctl -n porch-demo rpkg init network-function --repository=management --workspace=v1 @@ -1362,7 +1362,7 @@ NAME PACKAGE WORKSPA management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 false Draft management ``` -This command creates a new PackageRevision CR in porch and also creates a branch called `network-function/v1` in our gitea `management` repo. Use the Gitea web UI to confirm that the branch has been created and note that it only has default content as yet. +This command creates a new *PackageRevision* CR in porch and also creates a branch called *network-function/v1* in our gitea *management* repo. Use the Gitea web UI to confirm that the branch has been created and note that it only has default content as yet. We now pull the package we have initialized from Porch. @@ -1401,13 +1401,13 @@ management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 network-function v1 ``` -Once we approve the package, the package is merged into the main branch in the `management` repo and the branch called `network-function/v1` in that repo is removed. Use the Gitea UI to verify this. We now have our blueprint package in our `management` repo and we can deploy this package into workload clusters. +Once we approve the package, the package is merged into the main branch in the *management* repo and the branch called *network-function/v1* in that repo is removed. Use the Gitea UI to verify this. We now have our blueprint package in our *management* repo and we can deploy this package into workload clusters. ### Blueprint with a Kpt pipeline -The second blueprint blueprint in the `blueprint` directory is called `network-function-auto-namespace`. This network function is exactly the same as the `network-function` package except that it has a Kpt function that automatically creates a namespace with the namespace configured in the `name` field in the `package-context.yaml` file. Note that no namespace is defined in the metadata of the `deployment.yaml` file of this Kpt package. +The second blueprint blueprint in the *blueprint* directory is called *network-function-auto-namespace*. This network function is exactly the same as the *network-function* package except that it has a Kpt function that automatically creates a namespace with the namespace configured in the name field in the *package-context.yaml* file. Note that no namespace is defined in the metadata of the *deployment.yaml* file of this Kpt package. -We use the same sequence of commands again to publish our blueprint package for `network-function-auto-namespace`. +We use the same sequence of commands again to publish our blueprint package for *network-function-auto-namespace*. ``` porchctl -n porch-demo rpkg init network-function-auto-namespace --repository=management --workspace=v1 @@ -1420,7 +1420,7 @@ cp blueprints/local-changes/network-function-auto-namespace/* blueprints/initial porchctl -n porch-demo rpkg push management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 blueprints/initialized/network-function-auto-namespace ``` -Examine the `drafts/network-function-auto-namespace/v1` branch in Gitea. Notice that the `set-namespace` Kpt finction in the pipeline in the `Kptfile` has set the namespace in the `deployment.yaml` file to the value `default-namespace-name`, which it read from the `package-context.yaml` file. +Examine the *drafts/network-function-auto-namespace/v1* branch in Gitea. Notice that the set-namespace Kpt function in the pipeline in the *Kptfile* has set the namespace in the *deployment.yaml* file to the value default-namespace-name, which it read from the *package-context.yaml* file. Now we propose and approve the package. @@ -1442,7 +1442,7 @@ management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 network-function-auto-name ### Blueprint with no Kpt pipelines -The process of deploying a blueprint package from our `management` repo clones the package, then modifies it for use on the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the `edge1` repo. Remember that the `edge1` repo is being monitored by Configsync from the `edge1` cluster, so once the package appears in the `edge1` repo on the management cluster, it will be pulled by Configsync and applied to the `edge1` cluster. +The process of deploying a blueprint package from our *management* repo clones the package, then modifies it for use on the workload cluster. The cloned package is then initialized, pushed, proposed, and approved onto the *edge1* repo. Remember that the *edge1* repo is being monitored by Configsync from the edge1 cluster, so once the package appears in the *edge1* repo on the management cluster, it will be pulled by Configsync and applied to the edge1 cluster. ``` porchctl -n porch-demo rpkg pull management-8b80738a6e0707e3718ae1db3668d0b8ca3f1c82 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp @@ -1461,7 +1461,7 @@ The package we created in the last section is cloned. We now remove the original rm tmp_packages_for_deployment/edge1-network-function-a.clone.tmp/.KptRevisionMetadata ``` -We use a kpt function to change the namespace that will be used for the deployment of the network function. +We use a *kpt* function to change the namespace that will be used for the deployment of the network function. ``` kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployment/edge1-network-function-a.clone.tmp -- namespace=edge1-network-function-a @@ -1472,7 +1472,7 @@ kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployme [info]: namespace "" updated to "edge1-network-function-a", 1 value(s) changed ``` -We now initialize and push the package to the `edge1` repo: +We now initialize and push the package to the *edge1* repo: ``` porchctl -n porch-demo rpkg init edge1-network-function-a --repository=edge1 --workspace=v1 @@ -1490,10 +1490,10 @@ NAME PACKAGE WORKSPACEN edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 false Draft edge1 ``` -You can verify that the package is in the `network-function-a/v1` branch of the deployment repo using the Gitea web UI. +You can verify that the package is in the *network-function-a/v1* branch of the deployment repo using the Gitea web UI. -Check that the `edge1-network-function-a` package is not deployed on the edge1 cluster yet: +Check that the *edge1-network-function-a* package is not deployed on the edge1 cluster yet: ``` export KUBECONFIG=~/.kube/kind-edge1-config @@ -1502,7 +1502,7 @@ No resources found in network-function-a namespace. ``` -We now propose and approve the deployment package, which merges the package to the `edge1` repo and further triggers Configsync to apply the package to the `edge1` cluster. +We now propose and approve the deployment package, which merges the package to the *edge1* repo and further triggers Configsync to apply the package to the edge1 cluster. ``` export KUBECONFIG=~/.kube/kind-management-config @@ -1518,7 +1518,7 @@ NAME PACKAGE WORKSPACEN edge1-d701be9b849b8b8724a6e052cbc74ca127b737c3 network-function-a v1 v1 true Published edge1 ``` -We can now check that the `network-function-a` package is deployed on the edge1 cluster and that the pod is running +We can now check that the *network-function-a* package is deployed on the edge1 cluster and that the pod is running ``` export KUBECONFIG=~/.kube/kind-edge1-config @@ -1536,7 +1536,7 @@ network-function-9779fc9f5-4rqp2 1/1 Running 0 44s ### Blueprint with a Kpt pipeline -The process for deploying a blueprint with a Kpt pipeline runs the Kpt pipeline automatically with whatever configuration we give it. Rather than explicitly running a Kpt function to change the namespace, we will specify the namespace as configuration and the pipeline will apply it to the deployment. +The process for deploying a blueprint with a *Kpt* pipeline runs the Kpt pipeline automatically with whatever configuration we give it. Rather than explicitly running a *Kpt* function to change the namespace, we will specify the namespace as configuration and the pipeline will apply it to the deployment. ``` porchctl -n porch-demo rpkg pull management-c97bc433db93f2e8a3d413bed57216c2a72fc7e3 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp @@ -1556,7 +1556,7 @@ We now remove the original metadata from the package. rm tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone.tmp/.KptRevisionMetadata ``` -The package we created in the last section is cloned. We now initialize and push the package to the `edge1` repo: +The package we created in the last section is cloned. We now initialize and push the package to the *edge1* repo: ``` porchctl -n porch-demo rpkg init edge1-network-function-auto-namespace-a --repository=edge1 --workspace=v1 @@ -1569,7 +1569,7 @@ rm -fr tmp_packages_for_deployment/edge1-network-function-auto-namespace-a.clone ``` -We now simply configure the namespace we want to apply. edit the `tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml` file and set the namespace to use: +We now simply configure the namespace we want to apply. edit the *tmp_packages_for_deployment/edge1-network-function-auto-namespace-a/package-context.yaml* file and set the namespace to use: ``` 8c8 @@ -1578,7 +1578,7 @@ We now simply configure the namespace we want to apply. edit the `tmp_packages_f > name: edge1-network-function-auto-namespace-a ``` -We now push the package to the `edge1` repo: +We now push the package to the *edge1* repo: ``` porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 tmp_packages_for_deployment/edge1-network-function-auto-namespace-a @@ -1590,9 +1590,9 @@ porchctl -n porch-demo rpkg push edge1-48997da49ca0a733b0834c1a27943f1a0e075180 porchctl -n porch-demo rpkg get --name edge1-network-function-auto-namespace-a ``` -You can verify that the package is in the `network-function-auto-namespace-a/v1` branch of the deployment repo using the Gitea web UI. You can see that the kpt pipeline fired and set the `edge1-network-function-auto-namespace-a` namespace in the `deployment.yaml` file on the `drafts/edge1-network-function-auto-namespace-a/v1` branch on the `edge1` repo in gitea. +You can verify that the package is in the *network-function-auto-namespace-a/v1* branch of the deployment repo using the Gitea web UI. You can see that the kpt pipeline fired and set the edge1-network-function-auto-namespace-a namespace in the *deployment.yaml* file on the *drafts/edge1-network-function-auto-namespace-a/v1* branch on the *edge1* repo in gitea. -Check that the `edge1-network-function-auto-namespace-a` package is not deployed on the edge1 cluster yet: +Check that the *edge1-network-function-auto-namespace-a* package is not deployed on the edge1 cluster yet: ``` export KUBECONFIG=~/.kube/kind-edge1-config @@ -1601,7 +1601,7 @@ No resources found in network-function-auto-namespace-a namespace. ``` -We now propose and approve the deployment package, which merges the package to the `edge1` repo and further triggers Configsync to apply the package to the `edge1` cluster. +We now propose and approve the deployment package, which merges the package to the *edge1* repo and further triggers Configsync to apply the package to the edge1 cluster. ``` export KUBECONFIG=~/.kube/kind-management-config @@ -1617,7 +1617,7 @@ NAME PACKAGE edge1-48997da49ca0a733b0834c1a27943f1a0e075180 edge1-network-function-auto-namespace-a v1 v1 true Published edge1 ``` -We can now check that the `network-function-auto-namespace-a` package is deployed on the edge1 cluster and that the pod is running +We can now check that the *network-function-auto-namespace-a* package is deployed on the edge1 cluster and that the pod is running ``` export KUBECONFIG=~/.kube/kind-edge1-config @@ -1660,7 +1660,7 @@ spec: - network-function-c ``` -In this very simple PackageVariant, the `network-function` package in the `management` repo is cloned into the `edge1` repo as the `network-function-b` and `network-function-c` package variants. +In this very simple PackageVariant, the *network-function* package in the *management* repo is cloned into the *edge1* repo as the *network-function-b* and *network-function-c* package variants. {{% alert title="Note" color="primary" %}} @@ -1694,8 +1694,8 @@ NAME PACKAGE WORKSPACEN edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 network-function-c packagevariant-1 false Draft edge1 ``` -We can see that our two new packages are created as draft packages on the edge1 repo. We can also examine the -PacakgeVariant CRs that have been created: +We can see that our two new packages are created as draft packages on the *edge1* repo. We can also examine the +*PacakgeVariant* CRs that have been created: ```bash kubectl get PackageVariant -n porch-demo @@ -1706,7 +1706,7 @@ network-function-c network-function-9779fc9f5-h7nsb ``` -It is also interesting to examine the yaml of the PackageVariant: +It is also interesting to examine the yaml of the *PackageVariant*: ```yaml kubectl get PackageVariant -n porch-demo -o yaml @@ -1799,8 +1799,8 @@ metadata: resourceVersion: "" ``` -We now want to customize and deploy our two packages. To do this we must pull the pacakges locally, render the kpt -functions, and then push the rendered packages back up to the `edge1` repo. +We now want to customize and deploy our two packages. To do this we must pull the pacakges locally, render the *kpt* +functions, and then push the rendered packages back up to the *edge1* repo. ```bash porchctl rpkg pull edge1-a31b56c7db509652f00724dd49746660757cd98a tmp_packages_for_deployment/edge1-network-function-b --namespace=porch-demo @@ -1812,7 +1812,7 @@ kpt fn eval --image=gcr.io/kpt-fn/set-namespace:v0.4.1 tmp_packages_for_deployme porchctl rpkg push edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 tmp_packages_for_deployment/edge1-network-function-c --namespace=porch-demo ``` -Check that the namespace has been updated on the two packages in the `edge1` repo using the Gitea web UI. +Check that the namespace has been updated on the two packages in the *edge1* repo using the Gitea web UI. Now our two packages are ready for deployment: @@ -1830,7 +1830,7 @@ porchctl rpkg approve edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 --namespace edge1-ee14f7ce850ddb0a380cf201d86f48419dc291f4 approved ``` -We can now check that the `network-function-b` and `network-function-c` packages are deployed on the edge1 cluster and +We can now check that the *network-function-b* and *network-function-c* packages are deployed on the edge1 cluster and that the pods are running ```bash @@ -1845,7 +1845,7 @@ network-function-c network-function-9779fc9f5-h7nsb ### Using a PackageVariantSet to automatically set the package name and package namespace -The PackageVariant CR defined as: +The *PackageVariant* CR defined as: ```yaml apiVersion: config.porch.kpt.dev/v1alpha2 @@ -1870,9 +1870,9 @@ spec: ``` -In this PackageVariant, the `network-function-auto-namespace` package in the `management` repo is cloned into the `edge1` repo as the `network-function-auto-namespace-x` and `network-function-auto-namespace-y` package variants, similar to the PackageVariant in `simple-variant.yaml`. +In this *PackageVariant*, the *network-function-auto-namespace* package in the *management* repo is cloned into the *edge1* repo as the *network-function-auto-namespace-x* and *network-function-auto-namespace-y* package variants, similar to the *PackageVariant* in *simple-variant.yaml*. -An extra `template` section provided for the repositories in the PackageVariant: +An extra template section provided for the repositories in the PackageVariant: ```yaml template: @@ -1880,20 +1880,20 @@ template: packageExpr: "target.package + '-cumulus'" ``` -This template means that each package in the `spec.targets.repositories..packageNames` list will have the suffix -`-cumulus` added to its name. This allows us to automatically generate unique package names. Applying the -PackageVariantSet also automatically sets a unique namespace for each network function because applying the -PackageVariantSet automatically triggers the Kpt pipeline in the `network-function-auto-namespace` Kpt package to +This template means that each package in the spec.targets.repositories..packageNames list will have the suffix +-cumulus added to its name. This allows us to automatically generate unique package names. Applying the +*PackageVariantSet* also automatically sets a unique namespace for each network function because applying the +*PackageVariantSet* automatically triggers the Kpt pipeline in the *network-function-auto-namespace* *Kpt* package to gerenate unique namespaces for each deployed package. {{% alert title="Note" color="primary" %}} -Many other mutatinos can be performed using a PackageVariantSet. Use `kubectl explain PackageVariantSet` to get help on -the structure of the PackageVariantSet CRD to see the various mutations that are possible. +Many other mutatinos can be performed using a *PackageVariantSet*. Use `kubectl explain PackageVariantSet` to get help on +the structure of the *PackageVariantSet* CRD to see the various mutations that are possible. {{% /alert %}} -Applying the PackageVariantSet creates the new packages as draft packages: +Applying the *PackageVariantSet* creates the new packages as draft packages: ```bash kubectl apply -f name-namespace-variant.yaml @@ -1918,23 +1918,23 @@ The suffix `x-cumulonimbus` and `y-cumulonimbus` has been palced on the package {{% /alert %}} -Examine the `edge1` repo on Giea and you should see two new draft branches. +Examine the *edge1* repo on Giea and you should see two new draft branches. - drafts/network-function-auto-namespace-x-cumulonimbus/packagevariant-1 - drafts/network-function-auto-namespace-y-cumulonimbus/packagevariant-1 In these packages, you will see that: -1. The package name has been generated as `network-function-auto-namespace-x-cumulonimbus` and - `network-function-auto-namespace-y-cumulonimbus`in all files in the packages -2. The namespace has been generated as `network-function-auto-namespace-x-cumulonimbus` and - `network-function-auto-namespace-y-cumulonimbus` respectively in the `demployment.yaml` files -3. The PackageVariant has set the `data.name` field as `network-function-auto-namespace-x-cumulonimbus` and - `network-function-auto-namespace-y-cumulonimbus` respectively in the `pckage-context.yaml` files +1. The package name has been generated as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus in all files in the packages +2. The namespace has been generated as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus respectively in the *demployment.yaml* files +3. The PackageVariant has set the data.name field as network-function-auto-namespace-x-cumulonimbus and + network-function-auto-namespace-y-cumulonimbus respectively in the *pckage-context.yaml* files This has all been performed automatically; we have not had to perform the `porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these chages as we had to in the -`simple-variant.yaml` case above. +*simple-variant.yaml* case above. Now, let us explore the packages further: @@ -1949,7 +1949,7 @@ edge1-77dbfed49b6cb0723b7c672b224de04c0cead67e network-function-auto-namespace ``` We can see that our two new packages are created as draft packages on the edge1 repo. We can also examine the -PacakgeVariant CRs that have been created: +*PacakgeVariant* CRs that have been created: ```bash kubectl get PackageVariant -n porch-demo @@ -1960,7 +1960,7 @@ network-function-edge1-network-function-b 38m network-function-edge1-network-function-c 38m ``` -It is also interesting to examine the yaml of a PackageVariant: +It is also interesting to examine the yaml of a *PackageVariant*: ```yaml kubectl get PackageVariant -n porch-demo network-function-auto-namespace-edge1-network-function-35079f9f -o yaml diff --git a/content/en/docs/porch/using-porch/porchctl-cli-guide.md b/content/en/docs/porch/using-porch/porchctl-cli-guide.md index c630a688..5b0aa121 100644 --- a/content/en/docs/porch/using-porch/porchctl-cli-guide.md +++ b/content/en/docs/porch/using-porch/porchctl-cli-guide.md @@ -12,7 +12,7 @@ When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved To use it locally, [download](https://github.com/nephio-project/porch/releases), unpack and add it to your PATH. -_Optional: Generate the autocompletion script for the specified shell to add to your profile._ +Optional: Generate the autocompletion script for the specified shell to add to your profile. ``` porchctl completion bash @@ -49,7 +49,7 @@ Use "porchctl [command] --help" for more information about a command. ``` -The `porchtcl` command is an administration command for acting on Porch `Repository` (repo) and `PackageRevision` (rpkg) CRs. +The `porchtcl` command is an administration command for acting on Porch *Repository* (repo) and *PackageRevision* (rpkg) CRs. The commands for administering repositories are: diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md index 8b3b2d0a..a5e0c330 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md @@ -6,7 +6,7 @@ description: --- -This document is focused on using Porch via the `kpt` CLI. +This document is focused on using Porch via the *kpt* CLI. Installation of Porch, including prerequisites, is covered in a [dedicated document](install-and-using-porch.md). @@ -14,15 +14,15 @@ Installation of Porch, including prerequisites, is covered in a [dedicated docum To use Porch, you will need: -* [`kpt`](https://kpt.dev) -* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) -* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE) +* [*kpt*](https://kpt.dev) +* [*kubectl*](https://kubernetes.io/docs/tasks/tools/#kubectl) +* [*gcloud*](https://cloud.google.com/sdk/gcloud) (if running on GKE) -Make sure that your `kubectl` context is set up for `kubectl` to interact with the correct Kubernetes instance (see +Make sure that your *kubectl* context is set up for *kubectl* to interact with the correct Kubernetes instance (see [installation instructions](install-and-using-porch.md) or the [running-locally](../running-porch/running-locally.md) guide for details). -To check whether `kubectl` is configured with your Porch cluster (or local instance), run: +To check whether *kubectl* is configured with your Porch cluster (or local instance), run: ```bash kubectl api-resources | grep porch @@ -41,21 +41,21 @@ functions porch.kpt.dev/v1alpha1 true Porch server manages the following resources: -1. `repositories`: a repository (Git or OCI) can be registered with Porch to support discovery or management of KRM +1. **repositories**: a repository (Git or OCI) can be registered with Porch to support discovery or management of KRM configuration packages in those repositories, or discovery of KRM functions in those repositories. -2. `packagerevisions`: a specific revision of a KRM configuration package managed by Porch in one of the registered - repositories. This resource represents a _metadata view_ of the KRM configuration package. -3. `packagerevisionresources`: this resource represents the contents of the configuration package (KRM resources +2. **packagerevisions**: a specific revision of a KRM configuration package managed by Porch in one of the registered + repositories. This resource represents a metadata view of the KRM configuration package. +3. **packagerevisionresources**: this resource represents the contents of the configuration package (KRM resources contained in the package) -4. `functions`: function resource represents a KRM function discovered in a repository registered with Porch. Functions +4. **functions**: function resource represents a KRM function discovered in a repository registered with Porch. Functions are only supported with OCI repositories. {{% alert title="Note" color="primary" %}} -`packagerevisions` and `packagerevisionresources` represent different _views_ of the same underlying KRM -configuration package. `packagerevisions` represents the package metadata, and `packagerevisionresources` represents the -package content. The matching resources share the same `name` (as well as API group and version: -`porch.kpt.dev/v1alpha1`) and differ in resource kind (`PackageRevision` and `PackageRevisionResources` respectively). +packagerevisions and packagerevisionresources represent different views of the same underlying KRM +configuration package. packagerevisions represents the package metadata, and packagerevisionresources represents the +package content. The matching resources share the same name (as well as API group and version: +*porch.kpt.dev/v1alpha1*) and differ in resource kind (*PackageRevision* and *PackageRevisionResources* respectively). {{% /alert %}} @@ -93,7 +93,7 @@ $ kpt alpha repo register \ All command line flags supported: * `--directory` - Directory within the repository where to look for packages. -* `--branch` - Branch in the repository where finalized packages are committed (defaults to `main`). +* `--branch` - Branch in the repository where finalized packages are committed (defaults to *main*). * `--name` - Name of the package repository Kubernetes resource. If unspecified, will default to the name portion (last segment) of the repository URL (`blueprint` in the example above) * `--description` - Brief description of the package repository. @@ -102,9 +102,9 @@ All command line flags supported: * `--repo-basic-username` - Username for repository authentication using basic auth. * `--repo-basic-password` - Password for repository authentication using basic auth. -Additionally, common `kubectl` command line flags for controlling aspects of +Additionally, common *kubectl* command line flags for controlling aspects of interaction with the Kubernetes apiserver, logging, and more (this is true for -all `kpt` CLI commands which interact with Porch). +all *kpt* CLI commands which interact with Porch). Use the `kpt alpha repo get` command to query registered repositories: @@ -116,7 +116,7 @@ blueprints git Package True https://github.com/platkrm/bluepr deployments git Package true True https://github.com/platkrm/deployments.git ``` -The `kpt alpha get` commands support common `kubectl` +The `kpt alpha get` commands support common *kubectl* [flags](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#formatting-output) to format output, for example `kpt alpha repo get --output=yaml`. @@ -129,7 +129,7 @@ $ kpt alpha repo unregister deployments --namespace default ## Package Discovery And Introspection The `kpt alpha rpkg` command group contains commands for interacting with packages managed by the Package Orchestration -service. the `r` prefix used in the command group name stands for 'remote'. +service. the r prefix used in the command group name stands for 'remote'. The `kpt alpha rpkg get` command list the packages in registered repositories: @@ -145,16 +145,16 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 ... ``` -The `LATEST` column indicates whether the package revision is the latest among the revisions of the same package. In the -output above, `v2` is the latest revision of `istions` package and `v1` is the latest revision of `basens` package. +The LATEST column indicates whether the package revision is the latest among the revisions of the same package. In the +output above, v2 is the latest revision of *istions* package and v1 is the latest revision of *basens* package. -The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Published`, `Draft` or -`Proposed`. +The LIFECYCLE column indicates the lifecycle stage of the package revision, one of: Published, Draft or +Proposed. -The `REVISION` column indicates the revision of the package. Revisions are assigned when a package is `Published` and -starts at `v1`. +The REVISION column indicates the revision of the package. Revisions are assigned when a package is Published and +starts at v1. -The `WORKSPACENAME` column indicates the workspace name of the package. The workspace name is assigned when a draft +The WORKSPACENAME column indicates the workspace name of the package. The workspace name is assigned when a draft revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be must be unique among package revisions in the same package. @@ -169,7 +169,7 @@ Therefore, the names of the Kubernetes resources representing package revisions Simple filtering of package revisions by name (substring) and revision (exact match) is supported by the CLI using -`--name` and `--revision` flags: +--name and --revision flags: ```bash $ kpt alpha rpkg get --name istio --revision=v2 @@ -178,7 +178,7 @@ NAME PACKAGE WORKSPACENAME REV blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints ``` -The common `kubectl` flags that control output format are available as well: +The common *kubectl* flags that control output format are available as well: ```bash $ kpt alpha rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml @@ -201,7 +201,7 @@ spec: The `kpt alpha rpkg pull` command can be used to read the package resources. -The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables +The command can be used to print the package revision resources as ResourceList to stdout, which enables [chaining](https://kpt.dev/book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe) evaluation of functions on the package revision pulled from the Package Orchestration server. @@ -258,7 +258,7 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 ... ``` -The new package is created in the `Draft` lifecycle stage. This is true also for all commands that create new package +The new package is created in the Draft lifecycle stage. This is true also for all commands that create new package revision (`init`, `clone` and `copy`). Additional flags supported by the `kpt alpha rpkg init` command are: @@ -270,7 +270,7 @@ Additional flags supported by the `kpt alpha rpkg init` command are: * `--site` - Link to page with information about the package. -Use `kpt alpha rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: +Use `kpt alpha rpkg clone` command to create a *downstream* package by cloning an *upstream* package: ```bash $ kpt alpha rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ @@ -307,11 +307,11 @@ The flags supported by the `kpt alpha rpkg clone` command are: package is located. * `--ref` - Ref in the upstream repository where the upstream package is located. This can be a branch, tag, or SHA. -* `--repository` - Repository to which package will be cloned (downstream +* `--repository` - Repository to which package will be cloned (*downstream* repository). * `--workspace` - Workspace to assign to the downstream package. * `--strategy` - Update strategy that should be used when updating this package; - one of: `resource-merge`, `fast-forward`, `force-delete-replace`. + one of: resource-merge, fast-forward, force-delete-replace. The `kpt alpha rpkg copy` command can be used to create a new revision of an existing package. It is a means to @@ -328,7 +328,7 @@ NAME PACKAGE WORKSPACENAME blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 istions v3 false Draft blueprints ``` -The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package _draft_: +The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package *draft*: ```bash $ kpt alpha rpkg pull \ @@ -376,9 +376,9 @@ blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 deleted ## Package Lifecycle and Approval Flow -Authoring is performed on the package revisions in the _Draft_ lifecycle stage. Before a package can be deployed or -cloned, it must be _Published_. The approval flow is the process by which the package is advanced from _Draft_ state -through _Proposed_ state and finally to _Published_ lifecycle stage. +Authoring is performed on the package revisions in the Draft lifecycle stage. Before a package can be deployed or +cloned, it must be Published. The approval flow is the process by which the package is advanced from Draft state +through Proposed state and finally to Published lifecycle stage. The commands used to manage package lifecycle stages include: @@ -386,7 +386,7 @@ The commands used to manage package lifecycle stages include: * `approve` - Approves a proposal to finalize a package revision. * `reject` - Rejects a proposal to finalize a package revision -In the [Authoring Packages](#authoring-packages) section above we created several _draft_ packages and in this section +In the [Authoring Packages](#authoring-packages) section above we created several draft packages and in this section we will create proposals for publishing some of them. ```bash @@ -416,7 +416,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Proposed deployments ``` -At this point, a person in _platform administrator_ role, or even an automated process, will review and either approve +At this point, a person in platform administrator role, or even an automated process, will review and either approve or reject the proposals. To aid with the decision, the platform administrator may inspect the package contents using the commands above, such as `kpt alpha rpkg pull`. @@ -442,12 +442,12 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments ``` -Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose -proposal was approved is now in _Published_ state. +Observe that the rejected proposal returned the package revision back to Draft lifecycle stage. The package whose +proposal was approved is now in Published state. ## Deploying a Package -Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named `sync` to +Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named sync to emphasize that Config Sync is the deploying mechanism and that configuration is being synchronized with the actuation target as a means of deployment) and include: From 2e9ddc872d4ddd4f942003ac55f1be54f3f4ed91 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Thu, 21 Nov 2024 10:51:10 +0100 Subject: [PATCH 54/74] Models and apis language corrections (#180) Signed-off-by: Michael Greaves --- content/en/docs/apis/_index.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/content/en/docs/apis/_index.md b/content/en/docs/apis/_index.md index 5c6cc7bf..3ab9d131 100644 --- a/content/en/docs/apis/_index.md +++ b/content/en/docs/apis/_index.md @@ -7,22 +7,23 @@ description: Reference for the Nephio models and APIs ## Overview -Nephio APIs primarily consist of a collection of Go API objects, CRDs and other KRM types, +Nephio APIs consist primarily of a collection of Go API objects, CRDs, and other KRM types, specified and maintained in the [Nephio API repository](https://github.com/nephio-project/api). -This page aims to give a high level overview of the objects that are available and their +This section aims to give a high-level overview of the objects that are available and their relationships, and is based on an [original document](https://docs.google.com/document/d/1-5nlpY4FbuhWtdKTvIqPOv4bWmA6zx6TdHoEfk9Jc_Q/edit) developed by Tal Liron. -The aim is to keep these diagrams as simple as possible for now and only convey the important aspects of the modelled -entities. As such they are intended to give a high-level overview of the entities and relationships that can be accessed -and modified via the Nephio API, and provide reference to detailed documentation, generated from the code, where -available. +The aim is to keep the diagrams as simple as possible for now and only convey the important aspects +of the modeled entities. +As such, they are intended to give a high-level overview of the entities and relationships that can +be accessed and modified via the Nephio API, and provide reference to detailed documentation, +generated from the code, where available. -## Topology and Network APIs +## Topology and network APIs -This is a high-level overview of the Nephio models and their relationships, with links to the relevant API documentation -where available, and to the source code where not. +This is a high-level overview of the Nephio models and their relationships, with links to the +relevant API documentation where available, and to the source code where not. ```mermaid flowchart TD @@ -67,8 +68,8 @@ flowchart TD ``` -The detailed API description is [here](topology-and-networking/) +A detailed API description can be found [here](topology-and-networking/). ## Porch -The detailed API description of Porch is [here](porch/) \ No newline at end of file +A detailed API description of Porch can be found [here](porch/). \ No newline at end of file From bd179a5efca384e89fb22e8ad7b5f586d3ce5612 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Thu, 21 Nov 2024 13:15:09 +0000 Subject: [PATCH 55/74] Remove Function CR refs (#182) The Function CRD and Repo content tyoe has been removed from Porch. This cleans up any remaining refs. --------- Co-authored-by: Gergely Csatari --- .../docs/porch/contributors-guide/_index.md | 40 ++--- .../porch/contributors-guide/dev-process.md | 10 -- .../contributors-guide/environment-setup.md | 1 - .../en/docs/porch/package-orchestration.md | 162 ++++++++---------- .../porch/running-porch/running-locally.md | 1 - .../porch/running-porch/running-on-GKE.md | 1 - .../using-porch/install-and-using-porch.md | 2 - .../porch/using-porch/usage-porch-kpt-cli.md | 96 +++++------ 8 files changed, 136 insertions(+), 177 deletions(-) diff --git a/content/en/docs/porch/contributors-guide/_index.md b/content/en/docs/porch/contributors-guide/_index.md index 47eb3f65..1c3a8c15 100644 --- a/content/en/docs/porch/contributors-guide/_index.md +++ b/content/en/docs/porch/contributors-guide/_index.md @@ -7,7 +7,7 @@ description: ## Changing Porch API -If you change the API resources, in *api/porch/.../*.go*, update the generated code by running: +If you change the API resources, in `api/porch/.../*.go`, update the generated code by running: ```sh make generate @@ -17,23 +17,23 @@ make generate Porch comprises of several software components: -* [API](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch +* [api](https://github.com/nephio-project/porch/tree/main/api): Definition of the KRM API supported by the Porch extension apiserver -* [*porchctl*](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of - Porch Repository and PackageRevision custom resources. -* [*apiserver*](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST - handlers, Porch main function -* [*engine*](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - +* [porchctl](https://github.com/nephio-project/porch/tree/main/cmd/porchctl): CLI command tool for administration of + Porch `Repository` and `PackageRevision` custom resources. +* [apiserver](https://github.com/nephio-project/porch/tree/main/pkg/apiserver): The Porch apiserver implementation, REST + handlers, Porch `main` function +* [engine](https://github.com/nephio-project/porch/tree/main/pkg/engine): Core logic of Package Orchestration - operations on package contents -* [*func*](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API -* [*repository*](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package -* [*git*](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository. -* [*oci*](https://github.com/nephio-project/porch/tree/main/pkg/oci): Integration with OCI repository. -* [*cache*](https://github.com/nephio-project/porch/tree/main/pkg/cache): Package caching. -* [*controllers*](https://github.com/nephio-project/porch/tree/main/controllers): Repository CRD. No controller; +* [func](https://github.com/nephio-project/porch/tree/main/func): KRM function evaluator microservice; exposes gRPC API +* [repository](https://github.com/nephio-project/porch/blob/main/pkg/repository): Repository integration package +* [git](https://github.com/nephio-project/porch/tree/main/pkg/git): Integration with Git repository. +* [oci](https://github.com/nephio-project/porch/tree/main/pkg/oci): Integration with OCI repository. +* [cache](https://github.com/nephio-project/porch/tree/main/pkg/cache): Package caching. +* [controllers](https://github.com/nephio-project/porch/tree/main/controllers): `Repository` CRD. No controller; Porch apiserver watches these resources for changes as repositories are (un-)registered. -* [*test*](https://github.com/nephio-project/porch/tree/main/test): Test Git Server for Porch e2e testing, and - [*e2e*](https://github.com/nephio-project/porch/tree/main/test/e2e) tests. +* [test](https://github.com/nephio-project/porch/tree/main/test): Test Git Server for Porch e2e testing, and + [e2e](https://github.com/nephio-project/porch/tree/main/test/e2e) tests. ## Running Porch @@ -68,7 +68,7 @@ Follow the [Running Porch Locally](../running-porch/running-locally.md) guide to ## Debugging -To debug Porch, run Porch locally [Running Porch Locally](../running-porch/running-locally.md), exit porch server running +To debug Porch, run Porch locally [running-locally.md](../running-porch/running-locally.md), exit porch server running in the shell, and launch Porch under the debugger. VSCode debug session is pre-configured in [launch.json](https://github.com/nephio-project/porch/blob/main/.vscode/launch.json). @@ -89,9 +89,9 @@ Some useful code pointers: ## Running Tests All tests can be run using `make test`. Individual tests can be run using `go test`. -End-to-End tests assume that Porch instance is running and KUBECONFIG is configured +End-to-End tests assume that Porch instance is running and `KUBECONFIG` is configured with the instance. The tests will automatically detect whether they are running against -Porch running on local machine or k8s cluster and will start Git server appropriately, +Porch running on local machien or k8s cluster and will start Git server appropriately, then run test suite against the Porch instance. ## Makefile Targets @@ -103,7 +103,7 @@ then run test suite against the Porch instance. * `make push-images`: builds and pushes Porch Docker images * `make deployment-config`: customizes configuration which installs Porch in k8s cluster with correct image names, annotations, service accounts. - The deployment-ready configuration is copied into *./.build/deploy* + The deployment-ready configuration is copied into `./.build/deploy` * `make deploy`: deploys Porch in the k8s cluster configured with current kubectl context * `make push-and-deploy`: builds, pushes Porch Docker images, creates deployment configuration, and deploys Porch * `make` or `make all`: builds and runs Porch [locally](../running-porch/running-locally.md) @@ -112,5 +112,5 @@ then run test suite against the Porch instance. ## VS Code [VS Code](https://code.visualstudio.com/) works really well for editing and debugging. -Just open VS Code from the root folder of the Porch repository and it will work fine. The folder contains the needed +Just open VSCode from the root folder of the Porch repository and it will work fine. The folder contains the needed configuration to Launch different functions of Porch. \ No newline at end of file diff --git a/content/en/docs/porch/contributors-guide/dev-process.md b/content/en/docs/porch/contributors-guide/dev-process.md index 6fe543e1..7d87992c 100644 --- a/content/en/docs/porch/contributors-guide/dev-process.md +++ b/content/en/docs/porch/contributors-guide/dev-process.md @@ -61,16 +61,6 @@ curl https://localhost:4443/apis/porch.kpt.dev/v1alpha1 -k "apiVersion": "v1", "groupVersion": "porch.kpt.dev/v1alpha1", "resources": [ - { - "name": "functions", - "singularName": "", - "namespaced": true, - "kind": "Function", - "verbs": [ - "get", - "list" - ] - }, { "name": "packagerevisionresources", "singularName": "", diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index dc3d35fa..1bec3256 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -116,7 +116,6 @@ packagerevs config.porch.kpt.dev/v1alpha1 packagevariants config.porch.kpt.dev/v1alpha1 true PackageVariant packagevariantsets config.porch.kpt.dev/v1alpha2 true PackageVariantSet repositories config.porch.kpt.dev/v1alpha1 true Repository -functions porch.kpt.dev/v1alpha1 true Function packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision packages porch.kpt.dev/v1alpha1 true PorchPackage diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index 9ae1b30c..fbc11186 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -8,7 +8,7 @@ description: ## Why Customers who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using -a [*kpt*](https://kpt.dev) CLI and *kpt* function ecosystem, including [functions catalog](https://catalog.kpt.dev/). +a [kpt](https://kpt.dev) CLI and kpt function ecosystem, including [functions catalog](https://catalog.kpt.dev/). Package authoring is possible using a variety of editors with [YAML](https://yaml.org/) support. That said, a delightful UI experience of WYSIWYG package authoring which supports broader package lifecycle, including package authoring with *guardrails*, approval workflow, package deployment, and more, is not yet available. @@ -20,40 +20,37 @@ building the delightful UI experience supporting the configuration lifecycle. This section briefly describes core concepts of package orchestration: -**Package**: Package is a collection of related configuration files containing configuration of [KRM][krm] -resources. Specifically, configuration packages are [*kpt* packages](https://kpt.dev/). +***Package***: Package is a collection of related configuration files containing configuration of [KRM][krm] +**resources**. Specifically, configuration packages are [kpt packages](https://kpt.dev/). -**Repository**: Repositories store packages or [functions][]. For example [git][] or [OCI][oci]. Functions may be -associated with repositories to enforce constraints or invariants on packages (guardrails). -([more details](#repositories)) +***Repository***: Repositories store packages. For example [git][] or [OCI][oci]. ([more details](#repositories)) -Packages are sequentially versioned; multiple versions of the same package may exist in a repository. -[more details](#package-versioning)) +Packages are sequentially ***versioned***; multiple versions of the same package may exist in a repository. +([more details](#package-versioning)) -A package may have a link (URL) to an upstream package (a specific version) from which it was cloned. +A package may have a link (URL) to an ***upstream package*** (a specific version) from which it was cloned. ([more details](#package-relationships)) Package may be in one of several lifecycle stages: -* **Draft** - package is being created or edited. The package contents can be modified but package is not ready to be +* ***Draft*** - package is being created or edited. The package contents can be modified but package is not ready to be used (i.e. deployed) -* **Proposed** - author of the package proposed that the package be published -* **Published** - the changes to the package have been approved and the package is ready to be used. Published +* ***Proposed*** - author of the package proposed that the package be published +* ***Published*** - the changes to the package have been approved and the package is ready to be used. Published packages can be deployed or cloned -**Function** (specifically, [KRM functions][krm functions]) can be applied to packages to mutate or validate resources +***Functions*** (specifically, [KRM functions][krm functions]) can be applied to packages to mutate or validate resources within them. Functions can be applied to a package to create specific package mutation while editing a package draft, -functions can be added to package's *Kptfile* [pipeline][], or associated with a repository to be applied to all packages -on changes. ([more details](#functions)) +functions can be added to package's Kptfile [pipeline][]. -A repository can be designated as deployment repository. Published packages in a deployment repository are +A repository can be designated as ***deployment repository***. *Published* packages in a deployment repository are considered deployment-ready. ([more details](#deployment)) ## Core Components of Configuration as Data Implementation -The Core implementation of Configuration as Data, CaD Core, is a set of components and APIs which collectively enable: +The Core implementation of Configuration as Data, *CaD Core*, is a set of components and APIs which collectively enable: -* Registration of repositories (Git, OCI) containing *kpt* packages or functions, and discovery of packages and functions +* Registration of repositories (Git, OCI) containing kpt packages and the discovery of packages * Porcelain package lifecycle, including authoring, versioning, deletion, creation and mutations of a package draft, process of proposing the package draft, and publishing of the approved package. * Package lifecycle operations such as: @@ -73,7 +70,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [*kpt*][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [kpt][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle @@ -86,8 +83,8 @@ Concepts briefly introduced above are elaborated in more detail in this section. ### Repositories -[*kpt*][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI -support to *kpt*. Initially, the Package Orchestration service will prioritize integration with [git][], and support for +[kpt][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI +support to kpt. Initially, the Package Orchestration service will prioritize integration with [git][], and support for additional repository types may be added in the future as required. Requirements applicable to all repositories include: ability to store packages, their versions, and sufficient metadata @@ -126,8 +123,8 @@ We plan to use a simple integer sequence to represent package versions. ### Package Relationships -*kpt* packages support the concept of upstream. When a package is cloned from another, the new package -(called downstream package) maintains an upstream link to the specific version of the package from which it was +Kpt packages support the concept of ***upstream***. When a package is cloned from another, the new package +(called ***downstream*** package) maintains an upstream link to the specific version of the package from which it was cloned. If a new version of the upstream package becomes available, the upstream link can be used to [update](https://kpt.dev/book/03-packages/05-updating-a-package) the downstream package. @@ -140,40 +137,19 @@ others can be used as well. Here we highlight some key attributes of the deployment mechanism and its integration within the CaD Core: -* Published packages in a deployment repository are considered ready to be deployed +* _Published_ packages in a deployment repository are considered ready to be deployed * Config Sync supports deploying individual packages and whole repositories. For Git specifically that translates to a requirement to be able to specify repository, branch/tag/ref, and directory when instructing Config Sync to deploy a package. -* Draft packages need to be identified in such a way that Config Sync can easily avoid deploying them. +* _Draft_ packages need to be identified in such a way that Config Sync can easily avoid deploying them. * Config Sync needs to be able to pin to specific versions of deployable packages in order to orchestrate rollouts and rollbacks. This means it must be possible to GET a specific version of a package. * Config Sync needs to be able to discover when new versions are available for deployment. -### Functions - -Functions, specifically [KRM functions][krm functions], are used in the CaD core to manipulate resources within -packages. - -* Similar to packages, functions are stored in repositories. Some repositories (such as OCI) are more suitable for - storing functions than others (such as Git). -* Function discovery will be aided by metadata associated with the function by which the function can advertise which - resources it acts on, whether the function is idempotent or not, whether it is a mutator or validator, etc. -* Function repositories can be registered and subsequently, user can discover functions from the registered repositories - and use them as follows: - -Function can be: - -* applied imperatively to a package draft to perform specific mutation to the package's resources or meta-resources - (*Kptfile* etc.) -* registered in the package's *Kptfile* function pipeline as a mutator or validator in order to be automatically run - as part of package rendering -* registered at the repository level as mutator or validator. Such function then applies to all packages in the - repository and is evaluated whenever a change to a package in the repository occurs. - ## Package Orchestration - Porch Having established the context of the CaD Core components and the overall architecture, the remainder of the document -will focus on Porch - Package Orchestration service. +will focus on **Porch** - Package Orchestration service. To reiterate the role of Package Orchestration service among the CaD Core components, it is: @@ -181,7 +157,7 @@ To reiterate the role of Package Orchestration service among the CaD Core compon * [Package Discovery](#package-discovery) * [Package Authoring](#package-authoring) and Lifecycle -In the following section we'll expand more on each of these areas. The term *client* used in these sections can be +In the following section we'll expand more on each of these areas. The term _client_ used in these sections can be either a person interacting with the UI such as a web application or a command-line tool, or an automated agent or process. @@ -209,7 +185,7 @@ The package discovery functionality of Package Orchestration service enables the * retrieve resources and metadata of an individual package, including latest version or any specific version or draft of a package, for the purpose of introspection of a single package or for comparison of contents of multiple versions of a package, or related packages -* enumerate upstream packages available for creating (cloning) a downstream package +* enumerate _upstream_ packages available for creating (cloning) a _downstream_ package * identify downstream packages that need to be upgraded after a change is made to an upstream package * identify all deployment-ready packages in a deployment repository that are ready to be synced to a deployment target by Config Sync @@ -223,28 +199,28 @@ The package discovery functionality of Package Orchestration service enables the The package authoring and lifecycle functionality of the package Orchestration service enables the client to: -* Create a package draft via one of the following means: +* Create a package _draft_ via one of the following means: - * an empty draft 'from scratch' (equivalent to [`kpt pkg init`](https://kpt.dev/reference/cli/pkg/init/)) - * clone of an upstream package (equivalent to [`kpt pkg get`](https://kpt.dev/reference/cli/pkg/get/)) from either a + * an empty draft 'from scratch' (equivalent to [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/)) + * clone of an upstream package (equivalent to [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/)) from either a registered upstream repository or from another accessible, unregistered, repository - * edit an existing package (similar to the CLI command(s) [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/) or - [`kpt pkg pull`](https://github.com/GoogleContainerTools/kpt/issues/2557)) + * edit an existing package (similar to the CLI command(s) [kpt fn source](https://kpt.dev/reference/cli/fn/source/) or + [kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557)) * roll back / restore a package to any of its previous versions - ([`kpt pkg pull`](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version) + ([kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version) -* Apply changes to a package draft. In general, mutations include adding/modifying/deleting any part of the package's +* Apply changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's contents. Some specific examples include: - * add/change/delete package metadata (i.e. some properties in the *Kptfile*) + * add/change/delete package metadata (i.e. some properties in the `Kptfile`) * add/change/delete resources in the package * add function mutators/validators to the package's [pipeline][] * invoke a function imperatively on the package draft to perform a desired mutation * add/change/delete sub-package * retrieve the contents of the package for arbitrary client-side mutations (equivalent to - [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/)) + [kpt fn source](https://kpt.dev/reference/cli/fn/source/)) * update/replace the package contents with new contents, for example results of a client-side mutations by a UI - (equivalent to [`kpt fn sink`](https://kpt.dev/reference/cli/fn/sink/)) + (equivalent to [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/)) * Rebase a package onto another upstream base package ([detail](https://github.com/GoogleContainerTools/kpt/issues/2548)) or onto a newer version of the same package (to @@ -254,9 +230,9 @@ The package authoring and lifecycle functionality of the package Orchestration s * merge conflicts, invalid package changes, guardrail violations * compliance of the drafted package with repository-wide invariants and guardrails -* Propose for a draft package be published. -* Apply an arbitrary decision criteria, and by a manual or automated action, approve (or reject) proposal of a draft - package to be published. +* Propose for a _draft_ package be _published_. +* Apply an arbitrary decision criteria, and by a manual or automated action, approve (or reject) proposal of a _draft_ + package to be _published_. * Perform bulk operations such as: * Assisted/automated update (upgrade, rollback) of groups of packages matching specific criteria (i.e. base package @@ -292,7 +268,7 @@ perform in order to satisfy requirements of the basic roles. For example, only p ### Porch Architecture -The Package Orchestration service, Porch is designed to be hosted in a [Kubernetes](https://kubernetes.io/) cluster. +The Package Orchestration service, **Porch** is designed to be hosted in a [Kubernetes](https://kubernetes.io/) cluster. The overall architecture is shown below, and includes also existing components (k8s apiserver and Config Sync). @@ -319,34 +295,33 @@ extension API server are: Resources implemented by Porch include: -* **PackageRevision** - represents the metadata of the configuration package revision stored in a package repository. -* **PackageRevisionResources** - represents the contents of the package revision -* **Function** - represents a [KRM function][krm functions] discovered in a registered function repository. +* `PackageRevision` - represents the _metadata_ of the configuration package revision stored in a _package_ repository. +* `PackageRevisionResources` - represents the _contents_ of the package revision -Note that each configuration package revision is represented by a pair of resources which each present a different +Note that each configuration package revision is represented by a _pair_ of resources which each present a different view (or [representation][] of the same underlying package revision. -Repository registration is supported by a Repository [custom resource][crds]. +Repository registration is supported by a `Repository` [custom resource][crds]. -Porch server itself comprises several key components, including: +**Porch server** itself comprises several key components, including: -* The **Porch aggregated apiserver** which implements the integration into the main Kubernetes apiserver, and directly - serves API requests for the PackageRevision, PackageRevisionResources and Function resources. -* Package orchestration engine which implements the package lifecycle operations, and package mutation workflows -* **CaD Library** which implements specific package manipulation algorithms such as package rendering (evaluation of - package's function pipeline), initialization of a new package, etc. The CaD Library is shared with *kpt* +* The *Porch aggregated apiserver* which implements the integration into the main Kubernetes apiserver, and directly + serves API requests for the `PackageRevision`, `PackageRevisionResources` resources. +* Package orchestration *engine* which implements the package lifecycle operations, and package mutation workflows +* *CaD Library* which implements specific package manipulation algorithms such as package rendering (evaluation of + package's function *pipeline*), initialization of a new package, etc. The CaD Library is shared with `kpt` where it likewise provides the core package manipulation algorithms. -* **Package cache** which enables both local caching, as well as abstract manipulation of packages and their contents +* *Package cache* which enables both local caching, as well as abstract manipulation of packages and their contents irrespectively of the underlying storage mechanism (Git, or OCI) -* **Repository adapters** for Git and OCI which implement the specific logic of interacting with those types of package +* *Repository adapters* for Git and OCI which implement the specific logic of interacting with those types of package repositories. -* **Function runtime** which implements support for evaluating [*kpt* functions][functions] and multi-tier cache of +* *Function runtime* which implements support for evaluating [kpt functions][functions] and multi-tier cache of functions to support low latency function evaluation #### Function Runner -Function runner is a separate service responsible for evaluating [**kpt** functions][functions]. Function runner exposes -a [gRPC](https://grpc.io/) endpoint which enables evaluating a *kpt* function on the provided configuration package. +**Function runner** is a separate service responsible for evaluating [kpt functions][functions]. Function runner exposes +a [gRPC](https://grpc.io/) endpoint which enables evaluating a kpt function on the provided configuration package. The gRPC technology was chosen for the function runner service because the [requirements](#grpc-api) that informed choice of KRM API for the Package Orchestration service do not apply. The function runner is an internal microservice, @@ -356,29 +331,29 @@ The function runner also maintains cache of functions to support low latency fun #### CaD Library -The [*kpt*](https://*kpt*.dev/) CLI already implements foundational package manipulation algorithms in order to provide the +The [kpt](https://kpt.dev/) CLI already implements foundational package manipulation algorithms in order to provide the command line user experience, including: -* [`kpt pkg init`](https://kpt.dev/reference/cli/pkg/init/) - create an empty, valid, KRM package -* [`kpt pkg get`](https://kpt.dev/reference/cli/pkg/get/) - create a downstream package by cloning an upstream package; +* [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/) - create an empty, valid, KRM package +* [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/) - create a downstream package by cloning an upstream package; set up the upstream reference of the downstream package -* [`kpt pkg update`](https://kpt.dev/reference/cli/pkg/update/) - update the downstream package with changes from new +* [kpt pkg update](https://kpt.dev/reference/cli/pkg/update/) - update the downstream package with changes from new version of upstream, 3-way merge -* [`kpt fn eval`](https://kpt.dev/reference/cli/fn/eval/) - evaluate a *kpt* function on a package -* [`kpt fn render`](https://kpt.dev/reference/cli/fn/render/) - render the package by executing the function pipeline of +* [kpt fn eval](https://kpt.dev/reference/cli/fn/eval/) - evaluate a kpt function on a package +* [kpt fn render](https://kpt.dev/reference/cli/fn/render/) - render the package by executing the function pipeline of the package and its nested packages -* [`kpt fn source`](https://kpt.dev/reference/cli/fn/source/) and [`kpt fn sink`](https://kpt.dev/reference/cli/fn/sink/) - - read package from local disk as a ResourceList and write package represented as ResourcesList into local disk +* [kpt fn source](https://kpt.dev/reference/cli/fn/source/) and [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/) - + read package from local disk as a `ResourceList` and write package represented as `ResourcesList` into local disk The same set of primitives form the foundational building blocks of the package orchestration service. Further, the package orchestration service combines these primitives into higher-level operations (for example, package orchestrator renders packages automatically on changes, future versions will support bulk operations such as upgrade of multiple packages, etc). -The implementation of the package manipulation primitives in *kpt* was refactored (with initial refactoring completed, and +The implementation of the package manipulation primitives in kpt was refactored (with initial refactoring completed, and more to be performed as needed) in order to: -* create a reusable CaD library, usable by both *kpt* CLI and Package Orchestration service +* create a reusable CaD library, usable by both kpt CLI and Package Orchestration service * create abstractions for dependencies which differ between CLI and Porch, most notable are dependency on Docker for function evaluation, and dependency on the local file system for package rendering. @@ -389,19 +364,20 @@ Over time, the CaD Library will provide the package manipulation primitives: * perform 3-way merge (update) * render - core package rendering algorithm using a pluggable function evaluator to support: - * function evaluation via Docker (used by *kpt* CLI) + * function evaluation via Docker (used by kpt CLI) * function evaluation via an RPC to a service or appropriate function sandbox * high-performance evaluation of trusted, built-in, functions without sandbox * heal configuration (restore comments after lossy transformation) -and both *kpt* CLI and Porch will consume the library. This approach will allow leveraging the investment already made -into the high quality package manipulation primitives, and enable functional parity between *KPT* CLI and Package +and both kpt CLI and Porch will consume the library. This approach will allow leveraging the investment already made +into the high quality package manipulation primitives, and enable functional parity between KPT CLI and Package Orchestration service. ## User Guide -Find the Porch User Guide in a dedicated [document](using-porch/usage-porch-kpt-cli.md). +Find the Porch User Guide in a dedicated +[document](https://github.com/kptdev/kpt/blob/main/site/guides/porch-user-guide.md). ## Open Issues/Questions diff --git a/content/en/docs/porch/running-porch/running-locally.md b/content/en/docs/porch/running-porch/running-locally.md index 0a2ec8f9..1d35427e 100644 --- a/content/en/docs/porch/running-porch/running-locally.md +++ b/content/en/docs/porch/running-porch/running-locally.md @@ -99,7 +99,6 @@ export KUBECONFIG=${PWD}/deployments/local/kubeconfig kubectl api-resources | grep porch repositories config.porch.kpt.dev/v1alpha1 true Repository -functions porch.kpt.dev/v1alpha1 true Function packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision ``` diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index 1c67a3dc..a450b072 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -96,7 +96,6 @@ Expected output will include: ```bash repositories config.porch.kpt.dev/v1alpha1 true Repository -functions porch.kpt.dev/v1alpha1 true Function packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision ``` diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index fc962d93..73a500ad 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -247,7 +247,6 @@ packagerevs config.porch.kpt.dev/v1alpha1 packagevariants config.porch.kpt.dev/v1alpha1 true PackageVariant packagevariantsets config.porch.kpt.dev/v1alpha2 true PackageVariantSet repositories config.porch.kpt.dev/v1alpha1 true Repository -functions porch.kpt.dev/v1alpha1 true Function packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision packages porch.kpt.dev/v1alpha1 true Package @@ -454,7 +453,6 @@ The full list of Nephio CRDs is as below: ```bash kubectl api-resources --api-group=porch.kpt.dev NAME SHORTNAMES APIVERSION NAMESPACED KIND -functions porch.kpt.dev/v1alpha1 true Function packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision packages porch.kpt.dev/v1alpha1 true Package diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md index 29f4887a..3938f887 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md @@ -6,7 +6,7 @@ description: --- -This document is focused on using Porch via the *kpt* CLI. +This document is focused on using Porch via the `kpt` CLI. Installation of Porch, including prerequisites, is covered in a [dedicated document](install-and-using-porch.md). @@ -14,21 +14,21 @@ Installation of Porch, including prerequisites, is covered in a [dedicated docum To use Porch, you will need: -* [*kpt*](https://kpt.dev) -* [*kubectl*](https://kubernetes.io/docs/tasks/tools/#kubectl) -* [*gcloud*](https://cloud.google.com/sdk/gcloud) (if running on GKE) +* [`kpt`](https://kpt.dev) +* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) +* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE) -Make sure that your *kubectl* context is set up for *kubectl* to interact with the correct Kubernetes instance (see +Make sure that your `kubectl` context is set up for `kubectl` to interact with the correct Kubernetes instance (see [installation instructions](install-and-using-porch.md) or the [running-locally](../running-porch/running-locally.md) guide for details). -To check whether *kubectl* is configured with your Porch cluster (or local instance), run: +To check whether `kubectl` is configured with your Porch cluster (or local instance), run: ```bash kubectl api-resources | grep porch ``` -You should see the following four resources listed: +You should see the following four resourceds listed: ```bash repositories config.porch.kpt.dev/v1alpha1 true Repository @@ -41,21 +41,19 @@ functions porch.kpt.dev/v1alpha1 true Porch server manages the following resources: -1. **repositories**: a repository (Git or OCI) can be registered with Porch to support discovery or management of KRM - configuration packages in those repositories, or discovery of KRM functions in those repositories. -2. **packagerevisions**: a specific revision of a KRM configuration package managed by Porch in one of the registered - repositories. This resource represents a metadata view of the KRM configuration package. -3. **packagerevisionresources**: this resource represents the contents of the configuration package (KRM resources +1. `repositories`: a repository (Git or OCI) can be registered with Porch to support discovery or management of KRM + configuration packages in those repositories. +2. `packagerevisions`: a specific revision of a KRM configuration package managed by Porch in one of the registered + repositories. This resource represents a _metadata view_ of the KRM configuration package. +3. `packagerevisionresources`: this resource represents the contents of the configuration package (KRM resources contained in the package) -4. **functions**: function resource represents a KRM function discovered in a repository registered with Porch. Functions - are only supported with OCI repositories. {{% alert title="Note" color="primary" %}} -packagerevisions and packagerevisionresources represent different views of the same underlying KRM -configuration package. packagerevisions represents the package metadata, and packagerevisionresources represents the -package content. The matching resources share the same name (as well as API group and version: -*porch.kpt.dev/v1alpha1*) and differ in resource kind (*PackageRevision* and *PackageRevisionResources* respectively). +`packagerevisions` and `packagerevisionresources` represent different _views_ of the same underlying KRM +configuration package. `packagerevisions` represents the package metadata, and `packagerevisionresources` represents the +package content. The matching resources share the same `name` (as well as API group and version: +`porch.kpt.dev/v1alpha1`) and differ in resource kind (`PackageRevision` and `PackageRevisionResources` respectively). {{% /alert %}} @@ -93,7 +91,7 @@ $ kpt alpha repo register \ All command line flags supported: * `--directory` - Directory within the repository where to look for packages. -* `--branch` - Branch in the repository where finalized packages are committed (defaults to *main*). +* `--branch` - Branch in the repository where finalized packages are committed (defaults to `main`). * `--name` - Name of the package repository Kubernetes resource. If unspecified, will default to the name portion (last segment) of the repository URL (`blueprint` in the example above) * `--description` - Brief description of the package repository. @@ -102,9 +100,9 @@ All command line flags supported: * `--repo-basic-username` - Username for repository authentication using basic auth. * `--repo-basic-password` - Password for repository authentication using basic auth. -Additionally, common *kubectl* command line flags for controlling aspects of +Additionally, common `kubectl` command line flags for controlling aspects of interaction with the Kubernetes apiserver, logging, and more (this is true for -all *kpt* CLI commands which interact with Porch). +all `kpt` CLI commands which interact with Porch). Use the `kpt alpha repo get` command to query registered repositories: @@ -116,7 +114,7 @@ blueprints git Package True https://github.com/platkrm/bluepr deployments git Package true True https://github.com/platkrm/deployments.git ``` -The `kpt alpha get` commands support common *kubectl* +The `kpt alpha get` commands support common `kubectl` [flags](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#formatting-output) to format output, for example `kpt alpha repo get --output=yaml`. @@ -129,7 +127,7 @@ $ kpt alpha repo unregister deployments --namespace default ## Package Discovery And Introspection The `kpt alpha rpkg` command group contains commands for interacting with packages managed by the Package Orchestration -service. the r prefix used in the command group name stands for 'remote'. +service. the `r` prefix used in the command group name stands for 'remote'. The `kpt alpha rpkg get` command list the packages in registered repositories: @@ -145,16 +143,16 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 ... ``` -The LATEST column indicates whether the package revision is the latest among the revisions of the same package. In the -output above, v2 is the latest revision of *istions* package and v1 is the latest revision of *basens* package. +The `LATEST` column indicates whether the package revision is the latest among the revisions of the same package. In the +output above, `v2` is the latest revision of `istions` package and `v1` is the latest revision of `basens` package. -The LIFECYCLE column indicates the lifecycle stage of the package revision, one of: Published, Draft or -Proposed. +The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Published`, `Draft` or +`Proposed`. -The REVISION column indicates the revision of the package. Revisions are assigned when a package is Published and -starts at v1. +The `REVISION` column indicates the revision of the package. Revisions are assigned when a package is `Published` and +starts at `v1`. -The WORKSPACENAME column indicates the workspace name of the package. The workspace name is assigned when a draft +The `WORKSPACENAME` column indicates the workspace name of the package. The workspace name is assigned when a draft revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be must be unique among package revisions in the same package. @@ -169,7 +167,7 @@ Therefore, the names of the Kubernetes resources representing package revisions Simple filtering of package revisions by name (substring) and revision (exact match) is supported by the CLI using ---name and --revision flags: +`--name` and `--revision` flags: ```bash $ kpt alpha rpkg get --name istio --revision=v2 @@ -178,7 +176,7 @@ NAME PACKAGE WORKSPACENAME REV blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints ``` -The common *kubectl* flags that control output format are available as well: +The common `kubectl` flags that control output format are available as well: ```bash $ kpt alpha rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml @@ -201,7 +199,7 @@ spec: The `kpt alpha rpkg pull` command can be used to read the package resources. -The command can be used to print the package revision resources as ResourceList to stdout, which enables +The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables [chaining](https://kpt.dev/book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe) evaluation of functions on the package revision pulled from the Package Orchestration server. @@ -258,7 +256,7 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 ... ``` -The new package is created in the Draft lifecycle stage. This is true also for all commands that create new package +The new package is created in the `Draft` lifecycle stage. This is true also for all commands that create new package revision (`init`, `clone` and `copy`). Additional flags supported by the `kpt alpha rpkg init` command are: @@ -270,7 +268,7 @@ Additional flags supported by the `kpt alpha rpkg init` command are: * `--site` - Link to page with information about the package. -Use `kpt alpha rpkg clone` command to create a *downstream* package by cloning an *upstream* package: +Use `kpt alpha rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: ```bash $ kpt alpha rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ @@ -307,11 +305,11 @@ The flags supported by the `kpt alpha rpkg clone` command are: package is located. * `--ref` - Ref in the upstream repository where the upstream package is located. This can be a branch, tag, or SHA. -* `--repository` - Repository to which package will be cloned (*downstream* +* `--repository` - Repository to which package will be cloned (downstream repository). * `--workspace` - Workspace to assign to the downstream package. * `--strategy` - Update strategy that should be used when updating this package; - one of: resource-merge, fast-forward, force-delete-replace. + one of: `resource-merge`, `fast-forward`, `force-delete-replace`. The `kpt alpha rpkg copy` command can be used to create a new revision of an existing package. It is a means to @@ -328,7 +326,7 @@ NAME PACKAGE WORKSPACENAME blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 istions v3 false Draft blueprints ``` -The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package *draft*: +The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package _draft_: ```bash $ kpt alpha rpkg pull \ @@ -376,9 +374,9 @@ blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 deleted ## Package Lifecycle and Approval Flow -Authoring is performed on the package revisions in the Draft lifecycle stage. Before a package can be deployed or -cloned, it must be Published. The approval flow is the process by which the package is advanced from Draft state -through Proposed state and finally to Published lifecycle stage. +Authoring is performed on the package revisions in the _Draft_ lifecycle stage. Before a package can be deployed or +cloned, it must be _Published_. The approval flow is the process by which the package is advanced from _Draft_ state +through _Proposed_ state and finally to _Published_ lifecycle stage. The commands used to manage package lifecycle stages include: @@ -386,7 +384,7 @@ The commands used to manage package lifecycle stages include: * `approve` - Approves a proposal to finalize a package revision. * `reject` - Rejects a proposal to finalize a package revision -In the [Authoring Packages](#authoring-packages) section above we created several draft packages and in this section +In the [Authoring Packages](#authoring-packages) section above we created several _draft_ packages and in this section we will create proposals for publishing some of them. ```bash @@ -416,7 +414,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Proposed deployments ``` -At this point, a person in platform administrator role, or even an automated process, will review and either approve +At this point, a person in _platform administrator_ role, or even an automated process, will review and either approve or reject the proposals. To aid with the decision, the platform administrator may inspect the package contents using the commands above, such as `kpt alpha rpkg pull`. @@ -442,18 +440,18 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments ``` -Observe that the rejected proposal returned the package revision back to Draft lifecycle stage. The package whose -proposal was approved is now in Published state. +Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose +proposal was approved is now in _Published_ state. ## Deploying a Package -Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named sync to +Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named `sync` to emphasize that Config Sync is the deploying mechanism and that configuration is being synchronized with the actuation target as a means of deployment) and include: * `create` - Creates a sync of a package in the deployment cluster. -* `del` - Deletes the package rootsync. -* `get` - Gets a rootsync resource with which package was deployed. +* `del` - Deletes the package RootSync. +* `get` - Gets a RootSync resource with which package was deployed. ```bash # Make sure Config Sync is configured to use multirepo mode @@ -472,7 +470,7 @@ $ kpt alpha sync create -ndefault \ --package=deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ sync-istions-clone -Created rootsync config-management-system/sync-istions-clone +Created RootSync config-management-system/sync-istions-clone # Get the status of the sync resource $ kpt alpha sync get sync-istions-clone -oyaml From a57d6ff0bb12c713107145d8854f7203b3bc27e5 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Mon, 25 Nov 2024 07:29:14 +0000 Subject: [PATCH 56/74] Adding documentation for TLS registries configuration (#183) Paired with [PR#139](https://github.com/nephio-project/porch/pull/139) adds documentation for configuring custom CA certificate integration for private TLS registries --------- Co-authored-by: Gergely Csatari Co-authored-by: JamesMcDermott Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../using-authenticated-private-registries.md | 106 ++++++++++++++---- 1 file changed, 87 insertions(+), 19 deletions(-) diff --git a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md index c0b7257e..4a92daff 100644 --- a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md +++ b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md @@ -1,15 +1,25 @@ --- -title: "Using authenticated private registries" +title: "Using authenticated private registries with the Porch function runner" type: docs weight: 4 description: "" --- -To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: +The Porch function runner pulls kpt function images from registries and uses them for rendering kpt packages in Porch. The function runner is set up by default to fetch kpt function images from public container registries such as [GCR](https://gcr.io/kpt-fn/) and the configuration options described here are not required for such public registries. -1. Creating a kubernetes secret using a JSON file according to the Docker config schema, containing valid credentials for each authenticated registry. +## 1. Configuring function runner to operate with private container registries + +This section describes how set up authentication for a private container registry containing kpt functions online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) that require authentication (username/password or token). + +To enable pulling of kpt function images from authenticated private registries by the Porch function runner the system requires: + +1. Creating a Kubernetes secret using a JSON file according to the Docker config schema, containing valid credentials for each authenticated registry. 2. Mounting this new secret as a volume on the function runner. -3. Providing the path of the mounted secret to the function runner using the argument `--registry-auth-secret-path` +3. Configuring private registry functionality in the function runner's arguments: + 1. Enabling the functionality using the argument *--enable-private-registries*. + 2. Providing the path and name of the mounted secret using the arguments *--registry-auth-secret-path* and *--registry-auth-secret-name* respectively. + +### 1.1 Kubernetes secret setup for private registry using docker config An example template of what a docker *config.json* file looks like is as follows below. The base64 encoded value *bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=* of the *auth* key decodes to *my_username:my_password*, which is the format used by the config when authenticating. @@ -50,43 +60,101 @@ metadata: type: kubernetes.io/dockerconfigjson ``` -Next you must mount the secret as a volume on the function runner deployment. Add the following snippet to the Deployment object in the *2-function-runner.yaml* file: +### 1.2 Mounting docker config secret to the function runner + +Next you must mount the secret as a volume on the function runner deployment. Add the following sections to the Deployment object in the *2-function-runner.yaml* file: ```yaml volumeMounts: - - mountPath: /pod-cache-config - name: pod-cache-config-volume - mountPath: /var/tmp/auth-secret name: docker-config readOnly: true volumes: - - name: pod-cache-config-volume - configMap: - name: pod-cache-config - name: docker-config secret: secretName: ``` -You may specify your desired `mountPath:` so long as the function runner can access it. +You may specify your desired paths for each `mountPath:` so long as the function runner can access them. {{% alert title="Note" color="primary" %}} The chosen `mountPath:` should use its own, dedicated sub-directory, so that it does not overwrite access permissions of the existing directory. For example, if you wish to mount on `/var/tmp` you should use `mountPath: /var/tmp/` etc. {{% /alert %}} -Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: +### 1.3 Configuring function runner environment variables for private registries + +Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: ```yaml command: - - /server - - --config=/config.yaml - - --enable-private-registry=true + - --enable-private-registries=true - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson - --registry-auth-secret-name= - - --functions=/functions - - --pod-namespace=porch-fn-system ``` -The `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments have default values of *false*, */var/tmp/auth-secret/.dockerconfigjson* and *auth-secret* respectively; however, these should be overridden to enable the functionality and match user specifications. +The `--enable-private-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments have default values of *false*, */var/tmp/auth-secret/.dockerconfigjson* and *auth-secret* respectively; however, these should be overridden to enable the functionality and match user specifications. + +With this last step, if your Porch package uses kpt function images stored in an private registry (for example `- image: ghcr.io/private-registry/set-namespace:customv2`), the function runner will now use the secret info to replicate your secret on the `porch-fn-system` namespace and specify it as an `imagePullSecret` for the function pods, as documented [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). + +## 2. Configuring function runner to use custom TLS for private container registries + +If your private container registry uses a custom certificate for TLS authentication then extra configuration is required for the function runner to integrate with. See below + +1. Creating a Kubernetes secret using TLS information valid for all private registries you wish to use. +2. Mounting the secret containing the registries' TLS information to the function runner similarly to step 2. +3. Enabling TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registries-tls* and *--tls-secret-path* respectively. + +### 2.1 Kubernetes secret layout for TLS certificate -With this last step, if your Porch package uses a custom kpt function image stored in an authenticated private registry (for example `- image: ghcr.io/private-registry/set-namespace:customv2`), the function runner will now use the secret info to replicate your secret on the `porch-fn-system` namespace and specify it as an `imagePullSecret` for the function pods, as documented [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/). +A typical secret containing TLS information will take on the a similar format to the following: + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: + namespace: porch-system +data: + : +type: kubernetes.io/tls +``` + +{{% alert title="Note" color="primary" %}} +The content in ** must be in PEM (Privacy Enhanced Mail) format, and the ** must be *ca.crt* or *ca.pem*. No other values are accepted. +{{% /alert %}} + +### 2.2 Mounting TLS certificate secret to the function runner + +The TLS secret must then be mounted onto the function runner similarly to how the docker config secret was done previously in section 1.2 + +```yaml + volumeMounts: + - mountPath: /var/tmp/tls-secret/ + name: tls-registry-config + readOnly: true +volumes: + - name: tls-registry-config + secret: + secretName: +``` + +### 2.3 Configuring function runner environment variables for TLS on private registries + +The *--enable-private-registries-tls* and *--tls-secret-path* variables are only required if a private registry has TLS enabled. They indicate to the function runner that it should attempt authentication to the registry using TLS, and should use the TLS certificate information found on the path provided in *--tls-secret-path*. + +```yaml +command: + - --enable-private-registries-tls=true + - --tls-secret-path=/var/tmp/tls-secret/ +``` + +The *--enable-private-registries-tls* and *--tls-secret-path* arguments have default values of *false* and */var/tmp/tls-secret/* respectively; however, these should be configured by the user and are only necessary when using a private registry secured with TLS. + +### Function runner logic flow when TLS registries are enabled + +It is important to note that enabling TLS registry functionality makes the function runner attempt connection to the registry provided in the porch file using the mounted TLS certificate. If this certificate is invalid for the provided registry, it will try again using the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" (e.g. GitHub). If this also fails, it will attempt to connect without TLS: if this last resort fails, it will return an error to the user. + +{{% alert title="Note" color="primary" %}} +It is vital that the user has pre-configured the Kubernetes node which the function runner is operating on with the same TLS certificate information as is used in the ** secret. If this is not configured correctly, then even if the certificate is correctly configured in the function runner, the kpt function will not run - the function runner will be able to pull the image, but the KRM function pod created to run the function will fail with the error *x509 certificate signed by unknown authority*. +This pre-configuration setup is heavily cluster/implementation-dependent - consult your cluster's specific documentation about adding self-signed certificates or private/internal CA certs to your cluster. +{{% /alert %}} From 3d3a6ffdc4cb942f187fa33628fb017cbbbd8650 Mon Sep 17 00:00:00 2001 From: Schweier Dominika Date: Mon, 25 Nov 2024 08:31:12 +0100 Subject: [PATCH 57/74] Removing TBD from documentation (#186) Signed-off-by: Dominika Schweier --- content/en/docs/architecture.md | 12 ------------ .../guides/install-guides/package-transformations.md | 2 +- 2 files changed, 1 insertion(+), 13 deletions(-) diff --git a/content/en/docs/architecture.md b/content/en/docs/architecture.md index 034e3dff..4533ede2 100644 --- a/content/en/docs/architecture.md +++ b/content/en/docs/architecture.md @@ -37,15 +37,3 @@ The controllers for OAI and Free5GC are represented here. Although they are vend ### Porch ![Nephio Porch Component View](/static/images/architecture/nephio-porch-component-view.png) - -### ConfigSync - -TBD - is this a component of Nephio or a dependency? - -## Deployment View - -TBD - -## Representative Use Cases - -TBD - use cases between the major components diff --git a/content/en/docs/guides/install-guides/package-transformations.md b/content/en/docs/guides/install-guides/package-transformations.md index 2ee6b102..d25f42e4 100644 --- a/content/en/docs/guides/install-guides/package-transformations.md +++ b/content/en/docs/guides/install-guides/package-transformations.md @@ -444,7 +444,7 @@ During creation of the package variant *kpt* package, the following transformati 1. The new mutator added to the *Kptfile* by the package variant adds the annotation nephio.org/cluster-name: lambda is added to every resource in the package. - 2. The existing annotation in the *Kptfile* (coming from the Kptfile in the parent *cluster-capi-kind* package) sets + 2. The existing annotation in the *Kptfile* (coming from the *Kptfile* in the parent *cluster-capi-kind* package) sets the value lambda of the spec.clusterName field in *workload-cluster.yaml* as the value of the metadata.name field in the *cluster.yaml* file. From 4b062bdde71973e360e81432032e6dd4208f8c52 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Mon, 25 Nov 2024 08:34:12 +0100 Subject: [PATCH 58/74] Language correction to the Guide. (#187) Signed-off-by: Michael Greaves --- content/en/docs/guides/_index.md | 15 +++++++++------ content/en/docs/guides/install-guides/_index.md | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/content/en/docs/guides/_index.md b/content/en/docs/guides/_index.md index 2b7e0ff7..80c7a66d 100644 --- a/content/en/docs/guides/_index.md +++ b/content/en/docs/guides/_index.md @@ -1,13 +1,16 @@ --- title: Guides -description: A collection of step by step Nephio guides. +description: A collection of Nephio guides. weight: 2 --- -{{% pageinfo %}} -This page is draft and the separation of the content to different categories is not done. -{{% /pageinfo %}} +The Nephio documentation provides a comprehensive collection of step-by-step guides. These guides +are complete worked examples made up of multiple tasks that guide the user through a relatively +simple but realistic scenario: building an application that uses some of your project’s features, +for example. If you have already created some examples for your project, you can base tutorials on +them. This section is optional. However, remember that, although you may not need this section at +first, having tutorials can be useful to help your users engage with your example code, especially +if there are aspects that need more explanation than you can easily provide in code comments. -* [Nephio install guides](./install-guides/): Help in installing Nephio in different environments -* [Nephio user guides](./user-guides/): Help in understanding the basics of Nephio and provides examples to deploy Network Functions (NF) via Nephio. +The Guides fall into three categories: install guides, user guides, and contributor guides. \ No newline at end of file diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md index 64925a50..fca9377d 100644 --- a/content/en/docs/guides/install-guides/_index.md +++ b/content/en/docs/guides/install-guides/_index.md @@ -1,7 +1,7 @@ --- title: Nephio install guides description: > - Demonstration Environment Installation + Guides to install Nephio in different environments weight: 1 --- From 03bd46b108aca03490ead64a5609c0e9a0ffeaf2 Mon Sep 17 00:00:00 2001 From: Schweier Dominika Date: Mon, 25 Nov 2024 08:36:12 +0100 Subject: [PATCH 59/74] Adding exceptions to the vale accept file (#188) Signed-off-by: Dominika Schweier --- .vale/config/vocabularies/Nephio/accept.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 2f0c64a9..9a53c83e 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -11,6 +11,7 @@ cabundle [Cc]onfigmap Codegen [Cc]loudified +CNI Containerlab CLI CR @@ -22,6 +23,7 @@ Crossplane Dockerfile Docsy envtest +[Ee]xecute [Ee]tcd gcloud Gitea @@ -35,6 +37,7 @@ GVKs [Hh]ostname [Hh]omebrew html +https [Kk]pt [Kk]ptfile kubeadm @@ -42,12 +45,14 @@ Kubebuilder kubectl kubelet Kubernetes +Kustomization Kustomize Libvirt MacBook MetalLB [Nn]amespace Nephio +nerdctl Netlify NF NFDeploy @@ -57,13 +62,22 @@ NFs Multus [Mm]ultivendor [Mm]ulticloud +[Mm]utator +mgmt Nginx +IdP OAuth +oc OCI +OIDC [Oo]nboarding [Oo]nboarded Okta +OpenID +objectSelector [Pp]arameterization +[Pp]ackageVariant +params parameterRef passwordless [Pp]kgserver @@ -71,6 +85,8 @@ Podman [Pp]orch [Pp]orchctl Postgres +PVC +PVCs [Rr]pkg rootsync SDK @@ -78,14 +94,17 @@ starlark stdout stderr [Ss]udo +[Ss]ubpackages TLS [Tt]riage [Tt]ko [Tt]oolchain +[Uu]buntu UI UIs URI URIs +upstreamlock [Uu]ntar vCPU VirtualBox From 2fc881b9f1729320977415fe752e403d348d7895 Mon Sep 17 00:00:00 2001 From: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Date: Wed, 27 Nov 2024 10:59:14 +0000 Subject: [PATCH 60/74] Added documentation for the load test script (#185) The PR for the load test script is here: https://github.com/nephio-project/porch/pull/141 --- .../porch/contributors-guide/dev-process.md | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/content/en/docs/porch/contributors-guide/dev-process.md b/content/en/docs/porch/contributors-guide/dev-process.md index 7d87992c..34c7fddd 100644 --- a/content/en/docs/porch/contributors-guide/dev-process.md +++ b/content/en/docs/porch/contributors-guide/dev-process.md @@ -174,6 +174,75 @@ E2E=1 go test -v ./test/e2e/cli -run TestPorch/rpkg-lifecycle ``` +## Run the load test + +A script is provided to run a Porch load test against the Kubernetes API server where *KUBECONFIG* points to. + +```bash +porch % scripts/run-load-test.sh -h + +run-load-test.sh - runs a load test on porch + + usage: run-load-test.sh [-options] + + options + -h - this help message + -s hostname - the host name of the git server for porch git repos + -r repo-count - the number of repos to create during the test, a positive integer + -p package-count - the number of packages to create in each repo during the test, a positive integer + -e package-revision-count - the number of packagerevisions to create on each package during the test, a positive integer + -f result-file - the file where the raw results will be stored, defaults to load_test_results.txt + -o repo-result-file - the file where the results by reop will be stored, defaults to load_test_repo_results.csv + -l log-file - the file where the test log will be stored, defaults to load_test.log + -y - dirty mode, do not clean up after tests +``` + +The load test creates, copies, proposes and approves `repo-count` repos, each with `package-count` packages +with `package-revision-count` package revisions created for each package. The script initializes or copies each +package revision in turn. It adds a pipleline with two "apply-replacements" kpt functions to the Kptfile of each +package revision. It updates the package revision, and then proposes and approves it. + +The load test script creates repos on the git server at `hostname`, so it's URL will be `http://nephio:secret@hostname:3000/nephio/`. +The script expects a git server to be running at that URL. + +The `result-file` is a text file containing the time it takes for a package to move from being initialized or +copied to being approved. It also records the time it takes to proppose-delete and delete each package revision. + +The `repo-result-file` is a csv file that tabulates the results from `result-file` into columns for each repository created. + +For example: + +```bash +porch % scripts/run-load-test.sh -s 172.18.255.200 -r 4 -p 2 -e 3 +running load test towards git server http://nephio:secret@172.18.255.200:3000/nephio/ + 4 repos will be created + 2 packages in each repo + 3 pacakge revisions in each package + results will be stored in "load_test_results.txt" + repo results will be stored in "load_test_repo_results.csv" + the log will be stored in "load_test.log" +load test towards git server http://nephio:secret@172.18.255.200:3000/nephio/ completed +``` + +In the load test above, a total of 24 package revisions were created and deleted. + +|REPO-1-TEST|REPO-1-TIME|REPO-2-TEST|REPO-2-TIME|REPO-3-TEST|REPO-3-TIME|REPO-4-TEST|REPO-4-TIME| +|-----------|-----------|-----------|-----------|-----------|-----------|-----------|-----------| +1:1|1.951846|1:1|1.922723|1:1|2.019615|1:1|1.992746 +1:2|1.762657|1:2|1.864306|1:2|1.873962|1:2|1.846436 +1:3|1.807281|1:3|1.930068|1:3|1.860375|1:3|1.881649 +2:1|1.829227|2:1|1.904997|2:1|1.956160|2:1|1.988209 +2:2|1.803494|2:2|1.912169|2:2|1.915905|2:2|1.902103 +2:3|1.816716|2:3|1.948171|2:3|1.931904|2:3|1.952902 +del-6a0b3...|.918442|del-e757b...|.904881|del-d39cd...|.944850|del-6222f...|.911060 +del-378a4...|.831815|del-9211c...|.866386|del-316a5...|.898638|del-31d9f...|.895919 +del-89073...|.874867|del-97d45...|.876450|del-830e0...|.905896|del-7d411...|.866947 +del-4756f...|.850528|del-c95db...|.903599|del-4c450...|.884997|del-587f8...|.842529 +del-9860a...|.887118|del-9c1b9...|1.018930|del-66ae...|.929470|del-6ae3d...|.905359 +del-a11e5...|.845834|del-71540...|.899935|del-8d1e8...|.891296|del-9e2bb...|.864382 +del-1d789...|.851242|del-ffdc3...|.897862|del-75e45...|.852323|del-82eef...|.916630 +del-8ae7e...|.872696|del-58097...|.894618|del-d164f...|.852093|del-9da24...|.849919 + ## Switching between tasks The `make run-in-kind`, `make run-in-kind-no-server` and `make run-in-kind-no-controller` commands can be executed right after each other. No clean-up or restart is required between them. The make scripts will intelligently do the necessary changes in your current porch deployment in kind (e.g. removing or re-adding the porch API server). From f6a59b315e1509adc1e18ae6b536b5a48c72a65a Mon Sep 17 00:00:00 2001 From: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Date: Thu, 28 Nov 2024 08:22:15 +0000 Subject: [PATCH 61/74] Rephrase text on Porch main document page (#189) Reword the outlook section of the document. --------- Co-authored-by: JamesMcDermott --- content/en/docs/porch/_index.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/en/docs/porch/_index.md b/content/en/docs/porch/_index.md index 80f3790b..9d381def 100644 --- a/content/en/docs/porch/_index.md +++ b/content/en/docs/porch/_index.md @@ -10,15 +10,14 @@ description: Documentation of Porch Porch is “kpt-as-a-service”, providing opinionated package management, manipulation, and lifecycle operations in a Kubernetes-based API. This allows automation of these operations using standard Kubernetes controller techniques. -Short for Package Orchestration. +"Porch" is short for "Package Orchestration". ## Porch in the Nephio architecture, history and outlook -Porch is a key component of the Nephio architecture and was originally developed in the +Porch is a key component of the Nephio architecture. It was originally developed in the [kpt](https://github.com/kptdev/kpt) project. When kpt was donated to the [CNCF](https://www.cncf.io/projects/kpt/) it was decided that Porch would not be part of the kpt project and the code was donated to Nephio. -Porch is now maintained by the Nephio community and it is a stable part of the Nephio R3 architecture. However there is -an active discucssion about the future of the project. It is possible that the current Porch component will be replaced -in the Nephio architecture with a different codebase implementing the same concepts but not in a backward compatible -way. Potential candidates such as [pkgserver](https://docs.pkgserver.dev/) are being discussed in the Nephio community. \ No newline at end of file +Porch is maintained by the Nephio community. Porch will evolve with Nephio and +its architecture and implementation will be updated to meet the functional and non-functional requirements on it +and on Nephio as a whole. \ No newline at end of file From c2e5b9478b27e1e353f19503459c12c8261290ee Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Wed, 4 Dec 2024 17:43:20 +0000 Subject: [PATCH 62/74] Clean up doc structure (#191) General documentation clean up and re org --------- Co-authored-by: Gergely Csatari --- README.md | 4 +-- content/en/docs/abbreviations.md | 24 ---------------- content/en/docs/apis/porch/_index.md | 2 +- .../apis/topology-and-networking/_index.md | 2 +- ...{glossary.md => glossary-abbreviations.md} | 28 +++++++++++++++++-- .../install-guides/common-components.md | 2 +- .../install-guides/explore-nephio-free5gc.md | 9 ++++-- .../guides/install-guides/install-on-byoc.md | 4 +-- .../guides/install-guides/install-on-gcp.md | 6 ++-- .../{webui.md => web-ui/_index.md} | 17 ++++------- .../{ => web-ui}/webui-auth-gcp.md | 0 .../{ => web-ui}/webui-auth-okta.md | 0 resources.md | 3 +- 13 files changed, 47 insertions(+), 54 deletions(-) delete mode 100644 content/en/docs/abbreviations.md rename content/en/docs/{glossary.md => glossary-abbreviations.md} (96%) rename content/en/docs/guides/install-guides/{webui.md => web-ui/_index.md} (89%) rename content/en/docs/guides/install-guides/{ => web-ui}/webui-auth-gcp.md (100%) rename content/en/docs/guides/install-guides/{ => web-ui}/webui-auth-okta.md (100%) diff --git a/README.md b/README.md index 8ef4ab89..0b24716e 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ the Markdown files hosted in the GitHub repo to generate the documentation websi ### Setting up the environment -1. The site is using Hugo as the documentation generating engine and as Hugo depends on Go in mudule handling you need to - have Go installed on your computer. Most Linux distributions have Go preinstalled, but some of them have a verstion that is too old +1. The site is using Hugo as the documentation generating engine and as Hugo depends on Go in module handling you need to + have Go installed on your computer. Most Linux distributions have Go preinstalled, but some of them have a version that is too old for Hugo. You should have at least version 1.18.0. You can install version 1.18 of go on an Ubuntu using the following commands: diff --git a/content/en/docs/abbreviations.md b/content/en/docs/abbreviations.md deleted file mode 100644 index 7b252737..00000000 --- a/content/en/docs/abbreviations.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Abbreviations -description: -weight: 3 ---- - -This page gives brief explanations of abbreviations used in the Nephio project. See also the -[Nephio Glossary](/content/en/docs/glossary.md) for more detailed descriptions of Nephio related terms. - -## Nephio Related Abbreviations -* NF: Network Function -* PV: Package Variant -* PVS: Package Variant Set - -## 5G 3GPP Related Abbreviations -* AMF: Access and Mobility Management Function -* SMF: Session Management Function -* UPF: User Plane Function -* AUSF: Authentication Server Function -* NRF: Network Repository Function -* UDR: Unified Data Repository -* UDM: Unified Data Management -* DNN: Data Network Name -* NAD: Network Attachment Definition diff --git a/content/en/docs/apis/porch/_index.md b/content/en/docs/apis/porch/_index.md index b56de354..a6e708e4 100644 --- a/content/en/docs/apis/porch/_index.md +++ b/content/en/docs/apis/porch/_index.md @@ -4,4 +4,4 @@ type: docs weight: 5 description: Reference for the Nephio Porch APIs --- -{{< iframe src="https://doc.crds.dev/github.com/nephio-project/porch@v2.0.0" sub="https://doc.crds.dev/github.com/nephio-project/porch@v2.0.0">}} +{{< iframe src="https://doc.crds.dev/github.com/nephio-project/porch@v3.0.4" sub="https://doc.crds.dev/github.com/nephio-project/porch@v3.0.4">}} diff --git a/content/en/docs/apis/topology-and-networking/_index.md b/content/en/docs/apis/topology-and-networking/_index.md index ed33b635..c505374c 100644 --- a/content/en/docs/apis/topology-and-networking/_index.md +++ b/content/en/docs/apis/topology-and-networking/_index.md @@ -4,4 +4,4 @@ type: docs weight: 5 description: Reference for the Nephio Topology and Networking APIs --- -{{< iframe src="https://doc.crds.dev/github.com/nephio-project/api@v2.0.0" sub="https://doc.crds.dev/github.com/nephio-project/api@v2.0.0">}} \ No newline at end of file +{{< iframe src="https://doc.crds.dev/github.com/nephio-project/api@v3.0.0" sub="https://doc.crds.dev/github.com/nephio-project/api@v3.0.0">}} \ No newline at end of file diff --git a/content/en/docs/glossary.md b/content/en/docs/glossary-abbreviations.md similarity index 96% rename from content/en/docs/glossary.md rename to content/en/docs/glossary-abbreviations.md index 318f3dc4..2ea2475d 100644 --- a/content/en/docs/glossary.md +++ b/content/en/docs/glossary-abbreviations.md @@ -1,14 +1,15 @@ --- -title: Glossary +title: Glossary and Abbreviations description: -weight: 4 +weight: 10 --- We use many terms in our Nephio discussions, coming from different domains including telecom, Kubernetes, configuration management, and our own -Nephio-specific terms. This glossary is intended to help clarify our usage of +[Nephio-specific](#nephio-related-abbreviations) terms. This glossary is intended to help clarify our usage of these terms. + ## Config See [Configuration](#configuration). @@ -369,3 +370,24 @@ configuration at scale. A workload is any application running on Kubernetes, including network functions. + +## Nephio Related Abbreviations + +* PV: Package Variant +* PVS: Package Variant Set + +## 5G 3GPP Related Abbreviations + +* NF: Network Function +* AMF: Access and Mobility Management Function +* SMF: Session Management Function +* UPF: User Plane Function +* AUSF: Authentication Server Function +* NRF: Network Repository Function +* UDR: Unified Data Repository +* UDM: Unified Data Management +* DNN: Data Network Name + +## Kubernetes Networking + +* NAD: Network Attachment Definition diff --git a/content/en/docs/guides/install-guides/common-components.md b/content/en/docs/guides/install-guides/common-components.md index 0cdc95cb..38fedd0b 100644 --- a/content/en/docs/guides/install-guides/common-components.md +++ b/content/en/docs/guides/install-guides/common-components.md @@ -118,4 +118,4 @@ kpt live apply stock-repos --reconcile-timeout=15m --output=table ## WebUI (Optional) Nephio WebUI is optional and to install it you can follow this -[document](/content/en/docs/guides/install-guides/webui.md) +[document](/content/en/docs/guides/install-guides/web-ui/_index.md) diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md index bdc7be43..ad95da9e 100644 --- a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md +++ b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md @@ -5,9 +5,12 @@ description: > weight: 6 --- -Concepts as [Operator](/content/en/docs/glossary.md#operator) and -[Controller](/content/en/docs/glossary.md#controller) and -[CR](/content/en/docs/glossary.md#custom-resource) have already been explained here. +Concepts as [Operator](../../glossary-abbreviations.md#operator) and + +[Controller](../../glossary-abbreviations.md#controller) and + +[CR](../../glossary-abbreviations.md#custom-resource) have already been explained here. + ## Deploy the operator to the cluster diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 22f30100..642f8e0b 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -136,8 +136,8 @@ LoadBalancer service, Ingress, or Route). The WebUI currently supports the following options: -- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) -- [OIDC with Okta](/content/en/docs/guides/install-guides/webui-auth-okta.md) +- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md) +- [OIDC with Okta](/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md) ### Nephio Stock Repositories diff --git a/content/en/docs/guides/install-guides/install-on-gcp.md b/content/en/docs/guides/install-guides/install-on-gcp.md index c37155de..d9cb88bd 100644 --- a/content/en/docs/guides/install-guides/install-on-gcp.md +++ b/content/en/docs/guides/install-guides/install-on-gcp.md @@ -1022,9 +1022,9 @@ git commit -m "Initial checking of nephio-mgmt" **Prior to deploying the package, we need to manually setup the secret for the WebUI.** -See [Google OAuth 2.0 or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) for details on how to -set up OAuth. In particular you need to [create the client ID](/content/en/docs/guides/install-guides/webui-auth-gcp.md#creating-an-oauth-20-client-id) -and the [secret](/content/en/docs/guides/install-guides/webui-auth-gcp.md#create-the-secret-in-the-cluster) +See [Google OAuth 2.0 or OIDC](/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md) for details on how to +set up OAuth. In particular you need to [create the client ID](/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md#creating-an-oauth-20-client-id) +and the [secret](/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md#create-the-secret-in-the-cluster) manually. The *nephio-webui* subpackage in *nephio-mgmt* is already set up for diff --git a/content/en/docs/guides/install-guides/webui.md b/content/en/docs/guides/install-guides/web-ui/_index.md similarity index 89% rename from content/en/docs/guides/install-guides/webui.md rename to content/en/docs/guides/install-guides/web-ui/_index.md index 82f96dea..3c61ca1b 100644 --- a/content/en/docs/guides/install-guides/webui.md +++ b/content/en/docs/guides/install-guides/web-ui/_index.md @@ -1,17 +1,10 @@ --- -title: Install WebUI +title: Installing the WebUI description: > - These instructions explain how to install the Nephio WebUI. -weight: 6 + These instructions explain how to install and configure the Nephio WebUI. +weight: 2 --- -{{% pageinfo %}} -This page is draft and the separation of the content to different categories is not clear. -{{% /pageinfo %}} - - -## Nephio WebUI - To install the WebUI, we simply install a different *kpt* package. First, we pull the package locally: ```bash @@ -54,8 +47,8 @@ service). Configuring authentication for the WebUI is specific to the particular cluster environment. Guides for different environments are below: -- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) -- [OIDC with Okta](/content/en/docs/guides/install-guides/webui-auth-okta.md) +- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md) +- [OIDC with Okta](/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md) Once that configuration is updated, you can proceed with the installation (note, this uses `inventory-policy=adopt`, since in the previous steps we may have created the namespace already). diff --git a/content/en/docs/guides/install-guides/webui-auth-gcp.md b/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md similarity index 100% rename from content/en/docs/guides/install-guides/webui-auth-gcp.md rename to content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md diff --git a/content/en/docs/guides/install-guides/webui-auth-okta.md b/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md similarity index 100% rename from content/en/docs/guides/install-guides/webui-auth-okta.md rename to content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md diff --git a/resources.md b/resources.md index a1ba9a8a..da5c286d 100644 --- a/resources.md +++ b/resources.md @@ -46,7 +46,6 @@ More tutorials are under discussion in * [SIG Release Meeting playlist](https://www.youtube.com/playlist?list=PLiW9_IXAWtks9Ys4Zs6wPRNEuQYAnWcg1) ## Other Resources -* The [Glossary](/content/en/docs/glossary.md) defines common terminology used in the Nephio +* The [Glossary & Abbreviations](content/en/docs/glossary-abbreviations.md) defines common terminology used in the Nephio project. * The [Nephio Learning Resources page](learning.md) lists some learning resources that are useful for the Nephio community -* The [Abbreviation Decoder page](/content/en/docs/abbreviations.md) explains common abbreviations used in the project. From 2ed16f2ebeaeaceb9d20166af84270f55a999b21 Mon Sep 17 00:00:00 2001 From: Liam Fallon <35595825+liamfallon@users.noreply.github.com> Date: Fri, 6 Dec 2024 09:29:21 +0000 Subject: [PATCH 63/74] Updates to documentation for Porch (#192) --- content/en/docs/porch/config-as-data.md | 14 ++--- .../en/docs/porch/package-orchestration.md | 58 ++++++++----------- 2 files changed, 31 insertions(+), 41 deletions(-) diff --git a/content/en/docs/porch/config-as-data.md b/content/en/docs/porch/config-as-data.md index c7c5def4..0b882807 100644 --- a/content/en/docs/porch/config-as-data.md +++ b/content/en/docs/porch/config-as-data.md @@ -30,8 +30,8 @@ configuration of infrastructure, policy, services, applications, etc.) which: A system based on CaD should observe the following key principles: -* secrets should be stored separately, in a secret-focused storage system - ([example](https://cloud.google.com/secret-manager)) +* secrets should be stored separately, in a secret-focused storage +system ([example](https://cert-manager.io/)) * stores a versioned history of configuration changes by change sets to bundles of related configuration data * relies on uniformity and consistency of the configuration format, including @@ -64,15 +64,15 @@ Our implementation of the Configuration as Data approach ( [kpt](https://kpt.dev), [Config Sync](https://cloud.google.com/anthos-config-management/docs/config-sync-overview), and [Package Orchestration](https://github.com/nephio-project/porch)) -build on the foundation of +is built on the foundation of [Kubernetes Resource Model](https://github.com/kubernetes/design-proposals-archive/blob/main/architecture/resource-management.md) (KRM). {{% alert title="Note" color="primary" %}} Even though KRM is not a requirement of Config as Data (just like -Python or Go templates or Jinja are not specifically requirements for -[IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)), the choice of +Python or Go templates or Jinja are not specifically +requirements for [IaC](https://en.wikipedia.org/wiki/Infrastructure_as_code)), the choice of another foundational config representation format would necessitate implementing adapters for all types of infrastructure and applications configured, including Kubernetes, CRDs, GCP resources and more. Likewise, choice @@ -106,7 +106,7 @@ and provides the following basic functionality: * fork (or clone) an existing package from one package repository (called upstream) to another (called downstream) * delete a package from a repository * associate a version with the package; guarantee immutability of packages with an assigned version -* incorporate changes from the new version of an upstream package into a new version of a downstream package +* incorporate changes from the new version of an upstream package into a new version of a downstream package (3 way merge) * revert to a prior version of a package ## Value @@ -115,8 +115,6 @@ The Config as Data approach enables some key value which is available in other configuration management approaches to a lesser extent or is not available at all. -CaD approach enables: - * simplified authoring of configuration using a variety of methods and sources * WYSIWYG interaction with configuration using a simple data serialization formation rather than a code-like format * layering of interoperable interface surfaces (notably GUI) over declarative configuration mechanisms rather than diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index fbc11186..091f10e2 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -7,14 +7,14 @@ description: ## Why -Customers who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using -a [kpt](https://kpt.dev) CLI and kpt function ecosystem, including [functions catalog](https://catalog.kpt.dev/). +People who want to take advantage of the benefits of [Configuration as Data](config-as-data.md) can do so today using +a [kpt](https://kpt.dev) CLI and the kpt function ecosystem, including its [functions catalog](https://catalog.kpt.dev/). Package authoring is possible using a variety of editors with [YAML](https://yaml.org/) support. That said, a delightful UI experience of WYSIWYG package authoring which supports broader package lifecycle, including package authoring with *guardrails*, approval workflow, package deployment, and more, is not yet available. -*Package Orchestration* service is part of the implementation of the Configuration as Data approach, and enables -building the delightful UI experience supporting the configuration lifecycle. +Porch *Package Orchestration* (Porch) is part of the Nephio implementation of a Configuration as Data approach. It offers an API and +a CLI that enables building that delightful UI experience for supporting the configuration lifecycle. ## Core Concepts @@ -51,14 +51,14 @@ considered deployment-ready. ([more details](#deployment)) The Core implementation of Configuration as Data, *CaD Core*, is a set of components and APIs which collectively enable: * Registration of repositories (Git, OCI) containing kpt packages and the discovery of packages -* Porcelain package lifecycle, including authoring, versioning, deletion, creation and mutations of a package draft, - process of proposing the package draft, and publishing of the approved package. +* Management of package lifecycles, including authoring, versioning, deletion, creation and mutations of a package draft, + process of proposing the package draft, and publishing of the approved package * Package lifecycle operations such as: * assisted or automated rollout of package upgrade when a new version of the upstream package version becomes - available + available (3 way merge) * rollback of a package to previous version -* Deployment of packages from deployment repositories and observability of their deployment status. +* Deployment of packages from deployment repositories and observability of their deployment status * Permission model that allows role-based access control ### High-Level Architecture @@ -70,7 +70,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [kpt][] - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [porchctl](using-porch/porchctl-cli-guide.md) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle @@ -83,7 +83,7 @@ Concepts briefly introduced above are elaborated in more detail in this section. ### Repositories -[kpt][] and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI +Porch and [Config Sync][] currently integrate with [git][] repositories, and there is an existing design to add OCI support to kpt. Initially, the Package Orchestration service will prioritize integration with [git][], and support for additional repository types may be added in the future as required. @@ -93,7 +93,7 @@ associated with package to capture: * package dependency relationships (upstream - downstream) * package lifecycle state (draft, proposed, published) * package purpose (base package) -* (optionally) even customer-defined attributes +* (optionally) customer-defined attributes At repository registration, customers must be able to specify details needed to store packages in appropriate locations in the repository. For example, registration of a Git repository must accept a branch and a directory. @@ -117,16 +117,15 @@ Packages are sequentially versioned. The important requirements are: * ability to compare any 2 versions of a package to be either "newer than", equal, or "older than" relationship * ability to support automatic assignment of versions * ability to support [optimistic concurrency][optimistic-concurrency] of package changes via version numbers -* simple model which easily supports automation +* a simple model which easily supports automation -We plan to use a simple integer sequence to represent package versions. +We use a simple integer sequence to represent package versions. ### Package Relationships Kpt packages support the concept of ***upstream***. When a package is cloned from another, the new package -(called ***downstream*** package) maintains an upstream link to the specific version of the package from which it was -cloned. If a new version of the upstream package becomes available, the upstream link can be used to -[update](https://kpt.dev/book/03-packages/05-updating-a-package) the downstream package. +(called the ***downstream*** package) maintains an upstream link to the specific version of the package from which it was +cloned. If a new version of the upstream package becomes available, the upstream link can be used to update the downstream package. ### Deployment @@ -191,9 +190,6 @@ The package discovery functionality of Package Orchestration service enables the by Config Sync * identify new versions of packages in a deployment repository that can be rolled out to a deployment target by Config Sync -* discover functions in registered repositories based on filtering criteria including containing repository, - applicability of a function to a specific package or specific resource type(s), function metadata (mutator/validator), - idempotency (function is idempotent/not), etc. ### Package Authoring @@ -201,29 +197,25 @@ The package authoring and lifecycle functionality of the package Orchestration s * Create a package _draft_ via one of the following means: - * an empty draft 'from scratch' (equivalent to [kpt pkg init](https://kpt.dev/reference/cli/pkg/init/)) - * clone of an upstream package (equivalent to [kpt pkg get](https://kpt.dev/reference/cli/pkg/get/)) from either a + * an empty draft 'from scratch' (`porchctl rpkg init`) + * clone of an upstream package (`porchctl rpkg clone`) from either a registered upstream repository or from another accessible, unregistered, repository - * edit an existing package (similar to the CLI command(s) [kpt fn source](https://kpt.dev/reference/cli/fn/source/) or - [kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557)) + * edit an existing package (`porchctl rpkg pull`) * roll back / restore a package to any of its previous versions - ([kpt pkg pull](https://github.com/GoogleContainerTools/kpt/issues/2557) of a previous version) + (`porchctl rpkg pull` of a previous version) -* Apply changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's +* Push changes to a package _draft_. In general, mutations include adding/modifying/deleting any part of the package's contents. Some specific examples include: * add/change/delete package metadata (i.e. some properties in the `Kptfile`) * add/change/delete resources in the package - * add function mutators/validators to the package's [pipeline][] - * invoke a function imperatively on the package draft to perform a desired mutation + * add function mutators/validators to the package's pipeline * add/change/delete sub-package - * retrieve the contents of the package for arbitrary client-side mutations (equivalent to - [kpt fn source](https://kpt.dev/reference/cli/fn/source/)) + * retrieve the contents of the package for arbitrary client-side mutations (`porchctl rpkg pull`) * update/replace the package contents with new contents, for example results of a client-side mutations by a UI - (equivalent to [kpt fn sink](https://kpt.dev/reference/cli/fn/sink/)) + (`porchctl rpkg push`) -* Rebase a package onto another upstream base package - ([detail](https://github.com/GoogleContainerTools/kpt/issues/2548)) or onto a newer version of the same package (to +* Rebase a package onto another upstream base package or onto a newer version of the same package (to aid with conflict resolution during the process of publishing a draft package) * Get feedback during package authoring, and assistance in recovery from: @@ -246,7 +238,7 @@ The package authoring and lifecycle functionality of the package Orchestration s An important goal of the Package Orchestration service is to support building of task-specific UIs. In order to deliver low latency user experience acceptable to UI interactions, the innermost authoring loop (depicted below) will require: -* high performance access to the package store (load/save package) w/ caching +* high performance access to the package store (load/save package) with caching * low latency execution of mutations and transformations on the package contents * low latency [KRM function][krm functions] evaluation and package rendering (evaluation of package's function pipelines) From 2feeb98b523fac02fe6d033f14c0b5c2009546a5 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 09:19:24 +0000 Subject: [PATCH 64/74] Improve doc site navigation (#193) Adding expandable dropdown fro menu sub sections Adding heading self links --- config.toml | 4 ++++ layouts/_default/_markup/render-heading.html | 1 + 2 files changed, 5 insertions(+) create mode 100644 layouts/_default/_markup/render-heading.html diff --git a/config.toml b/config.toml index 7b53925b..4640f158 100644 --- a/config.toml +++ b/config.toml @@ -143,6 +143,10 @@ breadcrumb_disable = false sidebar_search_disable = false +# Set to false to prevent the menu sub-sections from being foldable + +sidebar_menu_foldable = true + # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar navbar_logo = true diff --git a/layouts/_default/_markup/render-heading.html b/layouts/_default/_markup/render-heading.html new file mode 100644 index 00000000..d8326e6a --- /dev/null +++ b/layouts/_default/_markup/render-heading.html @@ -0,0 +1 @@ +{{ template "_default/_markup/td-render-heading.html" . }} \ No newline at end of file From 631004eac5010ac7368595c2e31d8e3eccf01fe2 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 09:34:24 +0000 Subject: [PATCH 65/74] Fix invalid @@ pkg urls (#195) Invalid @@ in pkg urls https://github.com/nephio-project/nephio/issues/825 --- .../guides/install-guides/common-dependencies.md | 6 +++--- .../install-guides/install-on-multiple-vm.md | 8 ++++---- .../install-guides/install-on-single-vm.md | 16 ++++++++-------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/content/en/docs/guides/install-guides/common-dependencies.md b/content/en/docs/guides/install-guides/common-dependencies.md index 75ed7b90..722a15d5 100644 --- a/content/en/docs/guides/install-guides/common-dependencies.md +++ b/content/en/docs/guides/install-guides/common-dependencies.md @@ -33,7 +33,7 @@ This component is a controller for applying configuration to routers and switches. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/optional/network-config@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/optional/network-config@origin/v3.0.0 kpt fn render network-config kpt live init network-config kpt live apply network-config --reconcile-timeout=15m --output=table @@ -44,7 +44,7 @@ kpt live apply network-config --reconcile-timeout=15m --output=table The resource backend provides IP and VLAN allocation. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/optional/resource-backend@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/optional/resource-backend@origin/v3.0.0 kpt fn render resource-backend kpt live init resource-backend kpt live apply resource-backend --reconcile-timeout=15m --output=table @@ -57,7 +57,7 @@ which are getting deployed or are already deployed on the cluster. Either you ca then you can follow below steps: ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@origin/v3.0.0 kpt fn render gitea kpt live init gitea kpt live apply gitea --reconcile-timeout 15m --output=table diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index bc5c46b7..d5c4e397 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -39,7 +39,7 @@ The below steps have to be repeated for each workload cluster: Install *config-sync* using: ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@origin/v3.0.0 kpt fn render configsync kpt live init configsync kpt live apply configsync --reconcile-timeout=15m --output=table @@ -73,7 +73,7 @@ porchctl repo register \ In case, you are using Gitea then you can use the following steps ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/repository@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/repository@origin/v3.0.0 kpt fn render kpt live init kpt live apply --reconcile-timeout=15m --output=table @@ -95,7 +95,7 @@ kpt live apply --reconcile-timeout=15m --output=table Get the *root-sync* *kpt* package and edit it: ```bash -kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@@origin/v3.0.0 +kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@origin/v3.0.0 ``` Change *./rootsync/rootsync.yaml* and point *spec.git.repo* to the edge git repository and the @@ -146,7 +146,7 @@ config-management-system mgmt ddc9676c997696d4a102a5cf2c67d0a0c459ceb3 Workload CRDs are required to manage network functions. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/workload-crds@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/workload-crds@origin/v3.0.0 kpt live init workload-crds kpt live apply workload-crds --reconcile-timeout=15m --output=table ``` diff --git a/content/en/docs/guides/install-guides/install-on-single-vm.md b/content/en/docs/guides/install-guides/install-on-single-vm.md index 1577e2ab..d63f18c7 100644 --- a/content/en/docs/guides/install-guides/install-on-single-vm.md +++ b/content/en/docs/guides/install-guides/install-on-single-vm.md @@ -55,7 +55,7 @@ While you may use other Git providers as well, Gitea is required in the R2 setup *nephio-install* directory, run: ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/gitea@origin/v3.0.0 kpt fn render gitea kpt live init gitea kpt live apply gitea --reconcile-timeout 15m --output=table @@ -79,7 +79,7 @@ For managing the Kubernetes cluster infrastructure, it is necessary to install [cert-manager project](https://cert-manager.io/) to generate certificates. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/cert-manager@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/cert-manager@origin/v3.0.0 kpt fn render cert-manager kpt live init cert-manager kpt live apply cert-manager --reconcile-timeout 15m --output=table @@ -88,7 +88,7 @@ kpt live apply cert-manager --reconcile-timeout 15m --output=table Once *cert-manager* is installed, you can proceed with the installation of Cluster API components ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi@origin/v3.0.0 kpt fn render cluster-capi kpt live init cluster-capi kpt live apply cluster-capi --reconcile-timeout 15m --output=table @@ -98,7 +98,7 @@ Cluster API uses infrastructure providers to provision cloud resources required resources with the Docker provider, it can be installed with the followed package. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi-infrastructure-docker@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi-infrastructure-docker@origin/v3.0.0 kpt fn render cluster-capi-infrastructure-docker kpt live init cluster-capi-infrastructure-docker kpt live apply cluster-capi-infrastructure-docker --reconcile-timeout 15m --output=table @@ -109,7 +109,7 @@ machines. These templates define the kubelet arguments, etcd and coreDNS configu things. ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi-kind-docker-templates@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/infra/capi/cluster-capi-kind-docker-templates@origin/v3.0.0 kpt fn render cluster-capi-kind-docker-templates kpt live init cluster-capi-kind-docker-templates kpt live apply cluster-capi-kind-docker-templates --reconcile-timeout 15m --output=table @@ -124,7 +124,7 @@ The management or workload cluster both need *config-sync*, *root-sync* and a cl Install *config-sync* using: ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/nephio/core/configsync@origin/v3.0.0 kpt fn render configsync kpt live init configsync kpt live apply configsync --reconcile-timeout=15m --output=table @@ -135,7 +135,7 @@ kpt live apply configsync --reconcile-timeout=15m --output=table If you are using Gitea then you can use the following steps: ```bash -kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/repository@@origin/v3.0.0 +kpt pkg get --for-deployment https://github.com/nephio-project/catalog.git/distros/sandbox/repository@origin/v3.0.0 kpt fn render kpt live init kpt live apply --reconcile-timeout=15m --output=table @@ -158,7 +158,7 @@ You would need the name of the config-sync token to provide it to root-sync. Get the *root-sync* kpt package and edit it: ```bash -kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@@origin/v3.0.0 +kpt pkg get https://github.com/nephio-project/catalog.git/nephio/optional/rootsync@origin/v3.0.0 ``` Change *./rootsync/rootsync.yaml* and point *spec.git.repo* to the edge git repository: From 56e2cadf52d8454864fef212f5f21802d4b1c9fa Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 15:26:04 +0000 Subject: [PATCH 66/74] Remove kpt alpha cli calls --- .../porch/running-porch/running-on-GKE.md | 33 +--- .../using-porch/install-and-using-porch.md | 4 +- .../porch/using-porch/usage-porch-kpt-cli.md | 143 ++++++------------ 3 files changed, 56 insertions(+), 124 deletions(-) diff --git a/content/en/docs/porch/running-porch/running-on-GKE.md b/content/en/docs/porch/running-porch/running-on-GKE.md index a450b072..4c896e2a 100644 --- a/content/en/docs/porch/running-porch/running-on-GKE.md +++ b/content/en/docs/porch/running-porch/running-on-GKE.md @@ -24,7 +24,7 @@ need: * A [GCP Project](https://console.cloud.google.com/projectcreate) * [gcloud](https://cloud.google.com/sdk/docs/install) * [kubectl](https://kubernetes.io/docs/tasks/tools/); you can install it via `gcloud components install kubectl` -* [kpt](https://kpt.dev/) +* [porchctl](https://github.com/nephio-project/porch/releases/download/main/porchctl.tgz) * Command line utilities such as *curl*, *tar* To build and run Porch on GKE, you will also need: @@ -32,7 +32,7 @@ To build and run Porch on GKE, you will also need: * A container registry which will work with your GKE cluster. [Artifact Registry](https://console.cloud.google.com/artifacts) or [Container Registry](https://console.cloud.google.com/gcr) work well though you can use others too. -* [go 1.17](https://go.dev/dl/) or newer +* [go 1.21](https://go.dev/dl/) or newer * [docker](https://docs.docker.com/get-docker/) * [Configured docker credential helper](https://cloud.google.com/sdk/gcloud/reference/auth/configure-docker) * [git](https://git-scm.com/) @@ -75,14 +75,14 @@ gcloud container clusters get-credentials --region us-central1 porch-dev To run a released version of Porch, download the release config bundle from [Porch release page](https://github.com/nephio-project/porch/releases). -Untar and apply the *deployment-blueprint.tar.gz* config bundle. This will install: +Untar and apply the *porch_blueprint.tar.gz* config bundle. This will install: * Porch server * [Config Sync](https://kpt.dev/gitops/configsync/) ```bash mkdir porch-install -tar xzf ~/Downloads/deployment-blueprint.tar.gz -C porch-install +tar xzf ~/Downloads/porch_blueprint.tar.gz -C porch-install kubectl apply -f porch-install kubectl wait deployment --for=condition=Available porch-server -n porch-system ``` @@ -136,7 +136,7 @@ IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy-no-sa ``` If you want to use a different repository, you can set IMAGE_REPO variable -(see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L32) for details). +(see [Makefile](https://github.com/nephio-project/porch/blob/main/Makefile#L33) for details). The `make push-and-deploy-no-sa` target will install Porch but not Config Sync. You can install Config Sync in your k8s cluster manually following the @@ -190,11 +190,7 @@ kubectl annotate serviceaccount porch-server -n porch-system \ iam.gke.io/gcp-service-account=porch-server@${GCP_PROJECT_ID}.iam.gserviceaccount.com ``` -<<<<<<< HEAD Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity -======= -Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity ->>>>>>> main service account annotations: ```bash @@ -210,7 +206,7 @@ kubectl api-resources | grep porch To register a repository, use the following command: ```bash -kpt alpha repo register --repo-workload-identity --namespace=default https://source.developers.google.com/p//r/ +porchctl repo register --repo-workload-identity --namespace=default https://source.developers.google.com/p//r/ ``` #### OCI @@ -248,20 +244,3 @@ gcloud iam service-accounts add-iam-policy-binding porch-sync@${GCP_PROJECT_ID}. --role roles/iam.workloadIdentityUser \ --member "serviceAccount:${GCP_PROJECT_ID}.svc.id.goog[porch-system/porch-controllers]" ``` - -<<<<<<< HEAD -Build Porch, push images, and deploy Porch server and controllers using the `make` target that adds workload identity -======= -Build Porch, push images, and deploy porch server and controllers using the make target that adds workload identity ->>>>>>> main -service account annotations: - -```bash -IMAGE_TAG=$(git rev-parse --short HEAD) make push-and-deploy -``` - -As above, you can verify that Porch is running by querying the api-resources: - -```bash -kubectl api-resources | grep porch -``` \ No newline at end of file diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/using-porch/install-and-using-porch.md index 73a500ad..68a28b0c 100644 --- a/content/en/docs/porch/using-porch/install-and-using-porch.md +++ b/content/en/docs/porch/using-porch/install-and-using-porch.md @@ -7,7 +7,7 @@ description: "A tutorial to install and use Porch" This tutorial is a guide to installing and using Porch. It is based on the [Porch demo produced by Tal Liron of Google](https://github.com/tliron/klab/tree/main/environments/porch-demo). Users -should be very comfortable with using *git*, *docker*, and *kubernetes*. +should be comfortable using *git*, *docker*, and *kubernetes*. See also [the Nephio Learning Resource](https://github.com/nephio-project/docs/blob/main/learning.md) page for background help and information. @@ -1954,7 +1954,7 @@ In these packages, you will see that: network-function-auto-namespace-y-cumulonimbus respectively in the *pckage-context.yaml* files This has all been performed automatically; we have not had to perform the -`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these chages as we had to in the +`porchctl rpkg pull/kpt fn render/porchctl rpkg push` combination of commands to make these changes as we had to in the *simple-variant.yaml* case above. Now, let us explore the packages further: diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md index 3938f887..eff35cf1 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md @@ -28,13 +28,12 @@ To check whether `kubectl` is configured with your Porch cluster (or local insta kubectl api-resources | grep porch ``` -You should see the following four resourceds listed: +You should see the following api resources listed: ```bash repositories config.porch.kpt.dev/v1alpha1 true Repository packagerevisionresources porch.kpt.dev/v1alpha1 true PackageRevisionResources packagerevisions porch.kpt.dev/v1alpha1 true PackageRevision -functions porch.kpt.dev/v1alpha1 true Function ``` ## Porch Resources @@ -74,14 +73,14 @@ To use Porch with an OCI repository ([Artifact Registry](https://console.cloud.g (`iam.gke.io/gcp-service-account=porch-server@$(GCP_PROJECT_ID).iam.gserviceaccount.com`) to have appropriate level of access to your OCI repository. -Use the `kpt alpha repo register` command to register your repository with Porch: +Use the `porchctl repo register` command to register your repository with Porch: ```bash GITHUB_USERNAME= GITHUB_TOKEN= -$ kpt alpha repo register \ +$ porchctl repo register \ --namespace default \ --repo-basic-username=${GITHUB_USERNAME} \ --repo-basic-password=${GITHUB_TOKEN} \ @@ -102,37 +101,37 @@ All command line flags supported: Additionally, common `kubectl` command line flags for controlling aspects of interaction with the Kubernetes apiserver, logging, and more (this is true for -all `kpt` CLI commands which interact with Porch). +all `porchctl` CLI commands which interact with Porch). -Use the `kpt alpha repo get` command to query registered repositories: +Use the `porchctl repo get` command to query registered repositories: ```bash -$ kpt alpha repo get +$ porchctl repo get NAME TYPE CONTENT DEPLOYMENT READY ADDRESS blueprints git Package True https://github.com/platkrm/blueprints.git deployments git Package true True https://github.com/platkrm/deployments.git ``` -The `kpt alpha get` commands support common `kubectl` +The `porchctl get` commands support common `kubectl` [flags](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#formatting-output) to format output, for example -`kpt alpha repo get --output=yaml`. +`porchctl repo get --output=yaml`. -The command `kpt alpha repo unregister` can be used to unregister a repository: +The command `porchctl repo unregister` can be used to unregister a repository: ```bash -$ kpt alpha repo unregister deployments --namespace default +$ porchctl repo unregister deployments --namespace default ``` ## Package Discovery And Introspection -The `kpt alpha rpkg` command group contains commands for interacting with packages managed by the Package Orchestration +The `porchctl rpkg` command group contains commands for interacting with packages managed by the Package Orchestration service. the `r` prefix used in the command group name stands for 'remote'. -The `kpt alpha rpkg get` command list the packages in registered repositories: +The `porchctl rpkg get` command list the packages in registered repositories: ```bash -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-0349d71330b89ee48ac85167598ef23021fd0484 basens main main false Published blueprints @@ -146,14 +145,13 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 The `LATEST` column indicates whether the package revision is the latest among the revisions of the same package. In the output above, `v2` is the latest revision of `istions` package and `v1` is the latest revision of `basens` package. -The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Published`, `Draft` or -`Proposed`. +The `LIFECYCLE` column indicates the lifecycle stage of the package revision, one of: `Draft`, `Proposed` or `Published`. The `REVISION` column indicates the revision of the package. Revisions are assigned when a package is `Published` and starts at `v1`. The `WORKSPACENAME` column indicates the workspace name of the package. The workspace name is assigned when a draft -revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be +revision is created and is used as the branch name for proposed and draft package revisions. The workspace name must be unique among package revisions in the same package. {{% alert title="Note" color="primary" %}} @@ -170,7 +168,7 @@ Simple filtering of package revisions by name (substring) and revision (exact ma `--name` and `--revision` flags: ```bash -$ kpt alpha rpkg get --name istio --revision=v2 +$ porchctl rpkg get --name istio --revision=v2 NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 true Published blueprints @@ -179,7 +177,7 @@ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions v2 v2 The common `kubectl` flags that control output format are available as well: ```bash -$ kpt alpha rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml +$ porchctl rpkg get blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault -oyaml apiVersion: porch.kpt.dev/v1alpha1 kind: PackageRevision @@ -197,14 +195,14 @@ spec: ... ``` -The `kpt alpha rpkg pull` command can be used to read the package resources. +The `porchctl rpkg pull` command can be used to read the package resources. The command can be used to print the package revision resources as `ResourceList` to `stdout`, which enables [chaining](https://kpt.dev/book/04-using-functions/02-imperative-function-execution?id=chaining-functions-using-the-unix-pipe) evaluation of functions on the package revision pulled from the Package Orchestration server. ```bash -$ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault +$ porchctl rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList @@ -219,7 +217,7 @@ items: Or, the package contents can be saved on local disk for direct introspection or editing: ```bash -$ kpt alpha rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 ./istions -ndefault +$ porchctl rpkg pull blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 ./istions -ndefault $ find istions @@ -233,7 +231,7 @@ istions/package-context.yaml ## Authoring Packages -Several commands in the `kpt alpha rpkg` group support package authoring: +Several commands in the `porchctl rpkg` group support package authoring: * `init` - Initializes a new package revision in the target repository. * `clone` - Creates a clone of a source package in the target repository. @@ -241,15 +239,15 @@ Several commands in the `kpt alpha rpkg` group support package authoring: * `push` - Pushes package resources into a remote package. * `del` - Deletes one or more packages in registered repositories. -The `kpt alpha rpkg init` command can be used to initialize a new package revision. Porch server will create and +The `porchctl rpkg init` command can be used to initialize a new package revision. Porch server will create and initialize a new package (as a draft) and save it in the specified repository. ```bash -$ kpt alpha rpkg init new-package --repository=deployments --workspace=v1 -ndefault +$ porchctl rpkg init new-package --repository=deployments --workspace=v1 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 created -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments @@ -259,7 +257,7 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 The new package is created in the `Draft` lifecycle stage. This is true also for all commands that create new package revision (`init`, `clone` and `copy`). -Additional flags supported by the `kpt alpha rpkg init` command are: +Additional flags supported by the `porchctl rpkg init` command are: * `--repository` - Repository in which the package will be created. * `--workspace` - Workspace of the new package. @@ -268,24 +266,24 @@ Additional flags supported by the `kpt alpha rpkg init` command are: * `--site` - Link to page with information about the package. -Use `kpt alpha rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: +Use `porchctl rpkg clone` command to create a _downstream_ package by cloning an _upstream_ package: ```bash -$ kpt alpha rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ +$ porchctl rpkg clone blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 istions-clone \ --repository=deployments -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 created # Confirm the package revision was created -kpt alpha rpkg get deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault +porchctl rpkg get deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 false Draft deployments ``` -`kpt alpha rpkg clone` can also be used to clone packages that are in repositories not registered with Porch, for +`porchctl rpkg clone` can also be used to clone packages that are in repositories not registered with Porch, for example: ```bash -$ kpt alpha rpkg clone \ +$ porchctl rpkg clone \ https://github.com/GoogleCloudPlatform/blueprints.git cloned-bucket \ --directory=catalog/bucket \ --ref=main \ @@ -294,12 +292,12 @@ $ kpt alpha rpkg clone \ deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac created # Confirm the package revision was created -kpt alpha rpkg get deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac -ndefault +porchctl rpkg get deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments ``` -The flags supported by the `kpt alpha rpkg clone` command are: +The flags supported by the `porchctl rpkg clone` command are: * `--directory` - Directory within the upstream repository where the upstream package is located. @@ -312,24 +310,24 @@ The flags supported by the `kpt alpha rpkg clone` command are: one of: `resource-merge`, `fast-forward`, `force-delete-replace`. -The `kpt alpha rpkg copy` command can be used to create a new revision of an existing package. It is a means to +The `porchctl rpkg copy` command can be used to create a new revision of an existing package. It is a means to modifying an already published package revision. ```bash -$ kpt alpha rpkg copy \ +$ porchctl rpkg copy \ blueprints-421a5b5e43b03bc697d96f471929efc6ba3f54b3 \ --workspace=v3 -ndefault # Confirm the package revision was created -$ kpt alpha rpkg get blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault +$ porchctl rpkg get blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 istions v3 false Draft blueprints ``` -The `kpt alpha rpkg push` command can be used to update the resources (package contents) of a package _draft_: +The `porchctl rpkg push` command can be used to update the resources (package contents) of a package _draft_: ```bash -$ kpt alpha rpkg pull \ +$ porchctl rpkg pull \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault # Make edits using your favorite YAML editor, for example adding a new resource @@ -344,11 +342,11 @@ EOF # Push the updated contents to the Package Orchestration server, updating the # package contents. -$ kpt alpha rpkg push \ +$ porchctl rpkg push \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 ./new-package -ndefault # Confirm that the remote package now includes the new ConfigMap resource -$ kpt alpha rpkg pull deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +$ porchctl rpkg pull deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault apiVersion: config.kubernetes.io/v1 kind: ResourceList @@ -363,11 +361,11 @@ items: ... ``` -Package revision can be deleted using `kpt alpha rpkg del` command: +Package revision can be deleted using `porchctl rpkg del` command: ```bash # Delete package revision -$ kpt alpha rpkg del blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault +$ porchctl rpkg del blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 -ndefault blueprints-bf11228f80de09f1a5dd9374dc92ebde3b503689 deleted ``` @@ -389,7 +387,7 @@ we will create proposals for publishing some of them. ```bash # List package revisions to identify relevant drafts: -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -397,7 +395,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 istions-clone v1 deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 false Draft deployments # Propose two package revisions to be be published -$ kpt alpha rpkg propose \ +$ porchctl rpkg propose \ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 \ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 \ -ndefault @@ -406,7 +404,7 @@ deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 proposed deployments-c32b851b591b860efda29ba0e006725c8c1f7764 proposed # Confirm the package revisions are now Proposed -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -416,15 +414,15 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 At this point, a person in _platform administrator_ role, or even an automated process, will review and either approve or reject the proposals. To aid with the decision, the platform administrator may inspect the package contents using the -commands above, such as `kpt alpha rpkg pull`. +commands above, such as `porchctl rpkg pull`. ```bash # Approve a proposal to publish a package revision -$ kpt alpha rpkg approve deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault +$ porchctl rpkg approve deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 -ndefault deployments-11ca1db650fa4bfa33deeb7f488fbdc50cdb3b82 approved # Reject a proposal to publish a package revision -$ kpt alpha rpkg reject deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault +$ porchctl rpkg reject deployments-c32b851b591b860efda29ba0e006725c8c1f7764 -ndefault deployments-c32b851b591b860efda29ba0e006725c8c1f7764 rejected ``` @@ -432,7 +430,7 @@ Now the user can confirm lifecycle stages of the package revisions: ```bash # Confirm package revision lifecycle stages after approvals: -$ kpt alpha rpkg get +$ porchctl rpkg get NAME PACKAGE WORKSPACENAME REVISION LATEST LIFECYCLE REPOSITORY ... deployments-e06c2f6ec1afdd8c7d977fcf204e4d543778ddac cloned-bucket v1 false Draft deployments @@ -442,48 +440,3 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose proposal was approved is now in _Published_ state. - -## Deploying a Package - -Commands used in the context of deploying a package include are in the `kpt alpha sync` command group (named `sync` to -emphasize that Config Sync is the deploying mechanism and that configuration is being synchronized with the actuation -target as a means of deployment) and include: - -* `create` - Creates a sync of a package in the deployment cluster. -* `del` - Deletes the package RootSync. -* `get` - Gets a RootSync resource with which package was deployed. - -```bash -# Make sure Config Sync is configured to use multirepo mode -kubectl apply -f - < Date: Mon, 9 Dec 2024 18:36:44 +0000 Subject: [PATCH 67/74] Refactor porch cli and user guides --- .../guides/install-guides/install-on-byoc.md | 2 +- .../install-guides/install-on-multiple-vm.md | 2 +- content/en/docs/porch/_index.md | 4 +- .../environment-setup-vm.md | 2 +- .../contributors-guide/environment-setup.md | 4 +- .../en/docs/porch/package-orchestration.md | 2 +- .../{using-porch => user-guides}/_index.md | 2 +- .../adding-external-git-ca-bundle.md | 0 .../install-and-using-porch.md | 0 .../porchctl-cli-guide.md} | 59 +++++++++++--- .../using-authenticated-private-registries.md | 0 .../porch/using-porch/porchctl-cli-guide.md | 78 ------------------- 12 files changed, 58 insertions(+), 97 deletions(-) rename content/en/docs/porch/{using-porch => user-guides}/_index.md (61%) rename content/en/docs/porch/{using-porch => user-guides}/adding-external-git-ca-bundle.md (100%) rename content/en/docs/porch/{using-porch => user-guides}/install-and-using-porch.md (100%) rename content/en/docs/porch/{using-porch/usage-porch-kpt-cli.md => user-guides/porchctl-cli-guide.md} (85%) rename content/en/docs/porch/{using-porch => user-guides}/using-authenticated-private-registries.md (100%) delete mode 100644 content/en/docs/porch/using-porch/porchctl-cli-guide.md diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 642f8e0b..2643f3c2 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -21,7 +21,7 @@ your environment and choices. - *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/)on your workstation - *kpt* [installed](https://kpt.dev/installation/kpt-cli) on your workstation (version v1.0.0-beta.43 or later) - - *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation + - *porchctl* [installed](/content/en/docs/porch/user-guides/porchctl-cli-guide.md) on your workstation - Sudo-less *docker*, *podman*, or *nerdctl*. If using *podman* or *nerdctl*, you must set the [`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index bc5c46b7..79d563c1 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -19,7 +19,7 @@ weight: 7 * Kubernetes version 1.26+ * *kubectl* [installed ](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/) * *kpt* [installed](https://kpt.dev/installation/kpt-cli) (version v1.0.0-beta.43 or later) -* *porchctl* [installed](/content/en/docs/porch/using-porch/porchctl-cli-guide.md) on your workstation +* *porchctl* [installed](/content/en/docs/porch/user-guides/porchctl-cli-guide.md) on your workstation ## Installation of the management cluster diff --git a/content/en/docs/porch/_index.md b/content/en/docs/porch/_index.md index 9d381def..8425fd58 100644 --- a/content/en/docs/porch/_index.md +++ b/content/en/docs/porch/_index.md @@ -7,8 +7,8 @@ description: Documentation of Porch ## Overview - Porch is “kpt-as-a-service”, providing opinionated package management, manipulation, and lifecycle operations in a - Kubernetes-based API. This allows automation of these operations using standard Kubernetes controller techniques. +Porch is “kpt-as-a-service”, providing opinionated package management, manipulation, and lifecycle operations in a +Kubernetes-based API. This allows automation of these operations using standard Kubernetes controller techniques. "Porch" is short for "Package Orchestration". diff --git a/content/en/docs/porch/contributors-guide/environment-setup-vm.md b/content/en/docs/porch/contributors-guide/environment-setup-vm.md index b113725c..d64ecc56 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup-vm.md +++ b/content/en/docs/porch/contributors-guide/environment-setup-vm.md @@ -8,7 +8,7 @@ description: This tutorial gives short instructions on how to set up a development environment for Porch on a Nephio VM. It outlines the steps to get a [kind](https://kind.sigs.k8s.io/) cluster up and running to which a Porch instance running in Visual Studio Code can connect to and interact with. If you are not familiar with how porch works, it is highly recommended that you go -through the [Starting with Porch tutorial](../using-porch/install-and-using-porch.md) before going through this one. +through the [Starting with Porch tutorial](../user-guides/install-and-using-porch.md) before going through this one. ## Setting up the environment diff --git a/content/en/docs/porch/contributors-guide/environment-setup.md b/content/en/docs/porch/contributors-guide/environment-setup.md index 1bec3256..a790b750 100644 --- a/content/en/docs/porch/contributors-guide/environment-setup.md +++ b/content/en/docs/porch/contributors-guide/environment-setup.md @@ -8,7 +8,7 @@ description: This tutorial gives short instructions on how to set up a development environment for Porch on your local machine. It outlines the steps to get a [kind](https://kind.sigs.k8s.io/) cluster up and running to which a Porch instance running in Visual Studio Code can connect to and interact with. If you are not familiar with how porch works, it is highly recommended that you go -through the [Starting with Porch tutorial](../using-porch/install-and-using-porch.md) before going through this one. +through the [Starting with Porch tutorial](../user-guides/install-and-using-porch.md) before going through this one. {{% alert title="Note" color="primary" %}} @@ -123,7 +123,7 @@ packages porch.kpt.dev/v1alpha1 ## Create Repositories using your local Porch server -To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../using-porch/install-and-using-porch.md) +To connect Porch to Gitea, follow [step 7 in the Starting with Porch](../user-guides/install-and-using-porch.md) tutorial to create the repositories in Porch. You will notice logging messages in VS Code when you run the `kubectl apply -f porch-repositories.yaml` command. diff --git a/content/en/docs/porch/package-orchestration.md b/content/en/docs/porch/package-orchestration.md index 091f10e2..ff329248 100644 --- a/content/en/docs/porch/package-orchestration.md +++ b/content/en/docs/porch/package-orchestration.md @@ -70,7 +70,7 @@ At the high level, the Core CaD functionality comprises: * package repository management * package discovery, authoring and lifecycle management -* [porchctl](using-porch/porchctl-cli-guide.md) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages +* [porchctl](user-guides/porchctl-cli-guide.md) - a Git-native, schema-aware, extensible client-side tool for managing KRM packages * a GitOps-based deployment mechanism (for example [Config Sync][]), which distributes and deploys configuration, and provides observability of the status of deployed resources * a task-specific UI supporting repository management, package discovery, authoring, and lifecycle diff --git a/content/en/docs/porch/using-porch/_index.md b/content/en/docs/porch/user-guides/_index.md similarity index 61% rename from content/en/docs/porch/using-porch/_index.md rename to content/en/docs/porch/user-guides/_index.md index 10c4c350..c8a18209 100644 --- a/content/en/docs/porch/using-porch/_index.md +++ b/content/en/docs/porch/user-guides/_index.md @@ -1,5 +1,5 @@ --- -title: "Using Porch" +title: "Porch user guides" type: docs weight: 6 description: diff --git a/content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md b/content/en/docs/porch/user-guides/adding-external-git-ca-bundle.md similarity index 100% rename from content/en/docs/porch/using-porch/adding-external-git-ca-bundle.md rename to content/en/docs/porch/user-guides/adding-external-git-ca-bundle.md diff --git a/content/en/docs/porch/using-porch/install-and-using-porch.md b/content/en/docs/porch/user-guides/install-and-using-porch.md similarity index 100% rename from content/en/docs/porch/using-porch/install-and-using-porch.md rename to content/en/docs/porch/user-guides/install-and-using-porch.md diff --git a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md b/content/en/docs/porch/user-guides/porchctl-cli-guide.md similarity index 85% rename from content/en/docs/porch/using-porch/usage-porch-kpt-cli.md rename to content/en/docs/porch/user-guides/porchctl-cli-guide.md index eff35cf1..8b620077 100644 --- a/content/en/docs/porch/using-porch/usage-porch-kpt-cli.md +++ b/content/en/docs/porch/user-guides/porchctl-cli-guide.md @@ -1,22 +1,60 @@ --- -title: "Using Porch with the kpt CLI" +title: "Using the Porch CLI tool" type: docs -weight: 3 +weight: 2 description: --- +## Setting up the porchctl CLI -This document is focused on using Porch via the `kpt` CLI. +When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved into a new command called `porchctl`. -Installation of Porch, including prerequisites, is covered in a [dedicated document](install-and-using-porch.md). +To use it locally, [download](https://github.com/nephio-project/porch/releases/tag/main), unpack and add it to your PATH. -## Prerequisites +{{% alert title="Note" color="primary" %}} + +Installation of Porch, including its prerequisites, is covered in a [dedicated document](install-and-using-porch.md). + +{{% /alert %}} + +*Optional*: Generate the autocompletion script for the specified shell to add to your sh profile. + +``` +porchctl completion bash +``` + +The `porchtcl` command is an administration command for acting on Porch *Repository* (repo) and *PackageRevision* (rpkg) +CRs. + +The commands for administering repositories are: + +| Command | Description | +| --------------------- | ------------------------------ | +| `porchctl repo get` | List registered repositories. | +| `porchctl repo reg` | Register a package repository. | +| `porchctl repo unreg` | Unregister a repository. | -To use Porch, you will need: +The commands for administering package revisions are: -* [`kpt`](https://kpt.dev) -* [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) -* [`gcloud`](https://cloud.google.com/sdk/gcloud) (if running on GKE) +| Command | Description | +| ------------------------------ | --------------------------------------------------------------------------------------- | +| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | +| `porchctl rpkg clone` | Create a clone of an existing package revision. | +| `porchctl rpkg copy` | Create a new package revision from an existing one. | +| `porchctl rpkg del` | Delete a package revision. | +| `porchctl rpkg get` | List package revisions in registered repositories. | +| `porchctl rpkg init` | Initializes a new package in a repository. | +| `porchctl rpkg propose` | Propose that a package revision should be published. | +| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | +| `porchctl rpkg pull` | Pull the content of the package revision. | +| `porchctl rpkg push` | Push resources to a package revision. | +| `porchctl rpkg reject` | Reject a proposal to publish or delete a package revision. | +| `porchctl rpkg update` | Update a downstream package revision to a more recent revision of its upstream package. | + +## Using the porchctl CLI + +### Guide prerequisites +* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) Make sure that your `kubectl` context is set up for `kubectl` to interact with the correct Kubernetes instance (see [installation instructions](install-and-using-porch.md) or the [running-locally](../running-porch/running-locally.md) @@ -56,6 +94,7 @@ package content. The matching resources share the same `name` (as well as API gr {{% /alert %}} + ## Repository Registration To use Porch with a Git repository, you will need: @@ -439,4 +478,4 @@ deployments-c32b851b591b860efda29ba0e006725c8c1f7764 new-package v1 ``` Observe that the rejected proposal returned the package revision back to _Draft_ lifecycle stage. The package whose -proposal was approved is now in _Published_ state. +proposal was approved is now in _Published_ state. \ No newline at end of file diff --git a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md b/content/en/docs/porch/user-guides/using-authenticated-private-registries.md similarity index 100% rename from content/en/docs/porch/using-porch/using-authenticated-private-registries.md rename to content/en/docs/porch/user-guides/using-authenticated-private-registries.md diff --git a/content/en/docs/porch/using-porch/porchctl-cli-guide.md b/content/en/docs/porch/using-porch/porchctl-cli-guide.md deleted file mode 100644 index b0275b16..00000000 --- a/content/en/docs/porch/using-porch/porchctl-cli-guide.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "Using the Porch CLI" -type: docs -weight: 2 -description: ---- - -## Using the porchctl CLI - - -When Porch was ported to Nephio, the `kpt alpha rpkg` commands in kpt were moved into a new command called `porchctl`. - -To use it locally, [download](https://github.com/nephio-project/porch/releases), unpack and add it to your PATH. - -Optional: Generate the autocompletion script for the specified shell to add to your profile. - -``` -porchctl completion bash -``` - -Check that porchctl is working: - -``` -porchctl --help - -porchctl interacts with a Kubernetes API server with the Porch -server installed as an aggregated API server. It allows you to -manage Porch repository registrations and the packages within -those repositories. - -Usage: - porchctl [flags] - porchctl [command] - -Available Commands: - completion Generate the autocompletion script for the specified shell - help Help about any command - repo Manage package repositories. - rpkg Manage packages. - version Print the version number of porchctl - -Flags: - -h, --help help for porchctl - --log-flush-frequency duration Maximum number of seconds between log flushes (default 5s) - --truncate-output Enable the truncation for output (default true) - -v, --v Level number for the log level verbosity - -Use "porchctl [command] --help" for more information about a command. - -``` - -The `porchtcl` command is an administration command for acting on Porch *Repository* (repo) and *PackageRevision* (rpkg) -CRs. - -The commands for administering repositories are: - -| Command | Description | -| --------------------- | ------------------------------ | -| `porchctl repo get` | List registered repositories. | -| `porchctl repo reg` | Register a package repository. | -| `porchctl repo unreg` | Unregister a repository. | - -The commands for administering package revisions are: - -| Command | Description | -| ------------------------------ | --------------------------------------------------------------------------------------- | -| `porchctl rpkg approve` | Approve a proposal to publish a package revision. | -| `porchctl rpkg clone` | Create a clone of an existing package revision. | -| `porchctl rpkg copy` | Create a new package revision from an existing one. | -| `porchctl rpkg del` | Delete a package revision. | -| `porchctl rpkg get` | List package revisions in registered repositories. | -| `porchctl rpkg init` | Initializes a new package in a repository. | -| `porchctl rpkg propose` | Propose that a package revision should be published. | -| `porchctl rpkg propose-delete` | Propose deletion of a published package revision. | -| `porchctl rpkg pull` | Pull the content of the package revision. | -| `porchctl rpkg push` | Push resources to a package revision. | -| `porchctl rpkg reject` | Reject a proposal to publish or delete a package revision. | -| `porchctl rpkg update` | Update a downstream package revision to a more recent revision of its upstream package. | From 508c12f02dab06a313928d25c7984a493b25d27e Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Mon, 9 Dec 2024 19:01:53 +0000 Subject: [PATCH 68/74] Add workflow_dispatch trigger to link checker --- .github/workflows/check-links-md.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/check-links-md.yml b/.github/workflows/check-links-md.yml index 644c1506..d1e40606 100644 --- a/.github/workflows/check-links-md.yml +++ b/.github/workflows/check-links-md.yml @@ -1,6 +1,8 @@ name: "Check links of plain md files" -on: + +on: pull_request: + workflow_dispatch: jobs: docs: From 787d84036ab59027beaad04ea999871166b7e171 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Tue, 10 Dec 2024 13:25:23 +0000 Subject: [PATCH 69/74] Add missing APIs to be enabled in the documentation (#197) Added missing APIs that are required when setting up a new environment with the documentation steps. --- content/en/docs/guides/install-guides/install-on-gcp.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/docs/guides/install-guides/install-on-gcp.md b/content/en/docs/guides/install-guides/install-on-gcp.md index d9cb88bd..08c2e329 100644 --- a/content/en/docs/guides/install-guides/install-on-gcp.md +++ b/content/en/docs/guides/install-guides/install-on-gcp.md @@ -139,7 +139,9 @@ gcloud services enable krmapihosting.googleapis.com \ serviceusage.googleapis.com \ iam.googleapis.com \ gkehub.googleapis.com \ - anthosconfigmanagement.googleapis.com + anthosconfigmanagement.googleapis.com \ + anthos.googleapis.com \ + sourcerepo.googleapis.com ``` From 7acc09a520ae54f9fba4cbe0294ff0ac812cd987 Mon Sep 17 00:00:00 2001 From: mpgreaves <103421482+mpgreaves@users.noreply.github.com> Date: Thu, 12 Dec 2024 10:59:25 +0100 Subject: [PATCH 70/74] Language corrections for install guides. (#194) Signed-off-by: Michael Greaves --- .../en/docs/guides/install-guides/_index.md | 133 ++++++++++-------- 1 file changed, 72 insertions(+), 61 deletions(-) diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md index fca9377d..1c8d4ea1 100644 --- a/content/en/docs/guides/install-guides/_index.md +++ b/content/en/docs/guides/install-guides/_index.md @@ -1,7 +1,7 @@ --- -title: Nephio install guides +title: Nephio installation guides description: > - Guides to install Nephio in different environments + The following sections take you through the installation of Nephio in different environments. weight: 1 --- @@ -11,16 +11,18 @@ This page is draft and the separation of the content to different categories is ## Introduction -This Installation Guide will set up and run a Nephio demonstration environment. This environment is a single VM that -will be used in the exercises to simulate a topology with a Nephio management cluster and three workload clusters. +This installation guide will help you to set up and run a Nephio demonstration environment. This +environment is a single virtual machine (VM) that will be used in the exercises to simulate a +topology with a Nephio management cluster and three workload clusters. -## Installing on GCE +## Installing on the Google Compute Engine -### GCE Prerequisites +### GCE prerequisites -You will need a account in GCP and *gcloud* installed on your local environment. +To install Nephio on the Google Compute Engine (GCE), you will need an account in the Google Cloud +Platform (GCP). You will also need to have gcloud installed on your local environment. -### Create a Virtual Machine on GCE +### Create a virtual machine on the GCE ```bash gcloud compute instances create --machine-type e2-standard-16 \ @@ -33,39 +35,43 @@ gcloud compute instances create --machine-type e2-standard-16 \ {{% alert title="Note" color="primary" %}} -e2-standard-16 is recommended and e2-standard-8 is minimum. +We recommend that you use e2-standard-16. The minimum requirement is e2-standard-8. {{% /alert %}} -### Follow the Installation on GCE +### Following the progress of the installation on the GCE -If you want to watch the progress of the installation, give it about 30 seconds to reach a network accessible state, and -then ssh in and tail the startup script execution: +To watch the progress of the installation, you need to allow approximately 30 seconds for Nephio to +reach a network-accessible state. Then log in with ssh and investigate the script execution using +tail: ```bash gcloud compute ssh ubuntu@nephio-r3-e2e -- \ sudo journalctl -u google-startup-scripts.service --follow ``` -## Installing on a Pre-Provisioned VM +## Installing on a preprovisioned virtual machine -This install has been verified on VMs running on vSphere, OpenStack, AWS, and Azure. +This installation has been verified on VMs running on vSphere, OpenStack, AWS, and Azure. -### VM Prerequisites +### VM prerequisites -Order or create a VM with the following specification: +Order or create a VM with the following specifications: - Linux Flavour: Ubuntu-20.04-focal -- Minimum 8 cores and recommended 16 Cores +- a minimum of eight cores and recommended 16 Cores - 32 GB memory -- 200 GB disk size -- Default user with sudo passwordless permissions +- a disk size of 200 GB +- a default user with sudo passwordless permissions -**Configure a Route for Kubernetes** +**Configuring a route for Kubernetes** -In some installations, the IP range used by Kubernetes in the sandbox can clash with the IP address used by your VPN. In such cases, the VM will become unreachable during the sandbox installation. If you have this situation, add the route below on your VM. +In some installations, the IP range used by Kubernetes in the sandbox can clash with the IP address +that your VPN is using. In such cases, the VM will become unreachable during the sandbox +installation. If this situation arises, add the route detailed below on your VM. -Log onto your VM and run the following commands, replacing *\* and *\* with your VMs values: +Log on to your VM and run the following commands, replacing *\* and +*\* with your VM's values: ```bash sudo bash -c 'cat << EOF > /etc/netplan/99-cloud-init-network.yaml @@ -82,12 +88,14 @@ EOF' sudo netplan apply ``` -### Kick Off an Installation on VM -The commands below use default values for the GitHub path, GitHub branch/tag, username, K8s context, etc. See the table of variables below for information on how to set custom installation parameters and make changes to commands as you need to. +### Kicking off an installation on a virtual machine +The commands set out below use default values for the GitHub path, GitHub branch/tag, username, K8s +context, and so on. See the table of variables below for information on how to set custom +installation parameters and make changes to commands as required. -**Kind Cluster** +**Kind cluster** -Log onto your VM and run the following command : +Log on to your VM and run the following command : ```bash wget -O - https://raw.githubusercontent.com/nephio-project/test-infra/v3.0.0/e2e/provision/init.sh | \ @@ -97,13 +105,14 @@ sudo NEPHIO_DEBUG=false \ bash ``` -**Pre-installed K8s Cluster** +**Preinstalled K8s cluster** -Log onto your VM/System and run the following command: +Log on to your VM/system and run the following command: {{% alert title="Note" color="primary" %}} -The VM or System should be able to access the K8S API server via the kubeconfig file and have docker installed. -Docker is needed to run the KRM container functions specified in *rootsync* and *repository* packages. +The VM or system should be able to access the K8S API server via the kubeconfig file and have +Docker installed. You need Docker to run the KRM container functions specified in the *rootsync* +and *repository* packages. {{% /alert %}} @@ -120,31 +129,32 @@ sudo NEPHIO_DEBUG=false \ The following environment variables can be used to configure the installation: -| Variable | Values | Default Value | Description | +| Variable | Values | Default value | Description | |---------------------------|------------------| -------------------|------------------------------------------------------------------------------| -| *NEPHIO_USER* | userid | ubuntu | The user to install the sandbox on (must have sudo passwordless permissions) | -| *NEPHIO_DEBUG* | false or true | false | Controls debug output from the install | -| *NEPHIO_HOME* | path | /home/$NEPHIO_USER | The directory to check out the install scripts into | -| *RUN_E2E* | false or true | false | Specifies whether end-to-end tests should be ran or not | -| *DOCKERHUB_USERNAME* | alpha-num string | | Specifies the Docker Hub username | -| *DOCKERHUB_TOKEN* | alpha-num string | | Specifies the password or token | -| *NEPHIO_REPO* | URL | https://github.com/nephio-project/test-infra.git | URL of the repository to be used for installation | -| *NEPHIO_BRANCH* | branch | main/v3.0.0 | Tag or branch name to use in NEPHIO_REPO | -| *DOCKER_REGISTRY_MIRRORS* | list of URLs in JSON format | | List of docker registry mirrors in JSON format, or empty for no mirrors to be set. Example value: ``["https://docker-registry-remote.mycompany.com", "https://docker-registry-remote2.mycompany.com"]`` | -| *K8S_CONTEXT* | K8s context | kind-kind | Kubernetes context for existing non-kind cluster (gathered from `kubectl config get-contexts`, for example *kubernetes-admin@kubernetes*) | - -### Follow the Installation on VM +| *NEPHIO_USER* | userid | ubuntu | This is the user on which the sandbox needs to be installed (the user must have sudo passwordless permissions). | +| *NEPHIO_DEBUG* | true or false | false | This variable controls the debug output from the install. | +| *NEPHIO_HOME* | path | /home/$NEPHIO_USER | This is the directory into which the install scripts should be checked out. | +| *RUN_E2E* | true or false | false | This variable specifies whether or not end-to-end tests should be run. | +| *DOCKERHUB_USERNAME* | alpha-num string | | This variable specifies the Docker Hub username. | +| *DOCKERHUB_TOKEN* | alpha-num string | | This variable specifies the password or token. | +| *NEPHIO_REPO* | URL | https://github.com/nephio-project/test-infra.git | This variable specifies the URL of the repository to be used for installation. | +| *NEPHIO_BRANCH* | branch | main/v3.0.0 | This variable specifies the tag or branch name to use in NEPHIO_REPO | +| *DOCKER_REGISTRY_MIRRORS* | List of URLs in JSON format | | This variable specifies the list of Docker registry mirrors in JSON format. If there are no mirrors to be set, then the variable remains empty. Here are two example values: ``["https://docker-registry-remote.mycompany.com", "https://docker-registry-remote2.mycompany.com"]``| +| *K8S_CONTEXT* | K8s context | kind-kind | This variable defines the Kubernetes context for the existing non-kind cluster (gathered from `kubectl config get-contexts`, for example, *kubernetes-admin@kubernetes*). | + +### Following the progress of the installation on a virtual machine Monitor the installation on your terminal. -Log onto your VM using ssh on another terminal and use commands `docker` and `kubectl` to monitor the installation. +Log on to your VM using ssh on another terminal. Use the `docker` and `kubectl` commands to monitor +the installation. -## Access to the User Interfaces +## Access to the user interfaces -Once it is completed, ssh in and port forward the port to the UI (7007) and to Gitea's HTTP interface, if desired -(3000): +Once the installation is complete, log in with ssh and forward the port to the user interface (UI) +(7007) and to Gitea’s HTTP interface (3000), if desired: -Using GCE: +Using the GCE: ```bash gcloud compute ssh ubuntu@nephio-r3-e2e -- \ @@ -162,16 +172,17 @@ ssh @ \ kubectl port-forward --namespace=nephio-webui svc/nephio-webui 7007 ``` -You can now navigate to: -- [http://localhost:7007/config-as-data](http://localhost:7007/config-as-data) to browse the Nephio Web UI -- [http://localhost:3000/nephio](http://localhost:3000/nephio) to browse the Gitea UI +You can now navigate to the following URLs: +- [http://localhost:7007/config-as-data](http://localhost:7007/config-as-data), to browse the Nephio + web UI. +- [http://localhost:3000/nephio](http://localhost:3000/nephio), to browse the Gitea UI. -## Open Terminal +## Open terminal -You will probably want a second ssh window open to run `kubectl` commands, etc., without the port forwarding (which -would fail if you try to open a second ssh connection with that setting). +You may want a second ssh window open to run `kubectl` commands, and so on, without port forwarding +(which would fail if you tried to open a second ssh connection with that setting). -Using GCE: +Using the GCE: ```bash gcloud compute ssh ubuntu@nephio-r3-e2e @@ -183,15 +194,15 @@ Using a VM: ssh @ ``` -## Next Steps +## Next steps -* Step through the exercises +* Go through the following exercises: * [Free5GC Testbed Deployment and E2E testing with UERANSIM](/content/en/docs/guides/user-guides/exercise-1-free5gc.md) * [OAI Core and RAN Testbed Deployment and E2E testing](/content/en/docs/guides/user-guides/exercise-2-oai.md) -* Dig into the [user guide](/content/en/docs/guides/user-guides/_index.md) -* Nephio sandbox environment - * Install on pre-provisioned single VM - * Install on GCE +* Dig in to the [user guide](/content/en/docs/guides/user-guides/_index.md). +* Nephio sandbox environment: + * Install on preprovisioned single VM. + * Install on a GCE. * [Explore sandbox environment](/content/en/docs/guides/install-guides/explore-sandbox.md) * [Bring-Your-Own-Cluster](/content/en/docs/guides/install-guides/install-on-byoc.md) * [Install using vagrant on Windows (for development)](/content/en/docs/guides/install-guides/demo-vagrant-windows.md) From 3d80d9f1a776743dd6839b62c825e7b0cfaef6e1 Mon Sep 17 00:00:00 2001 From: Schweier Dominika Date: Mon, 16 Dec 2024 08:29:48 +0100 Subject: [PATCH 71/74] Adding more exceptions to the allow list (#198) Signed-off-by: Dominika Schweier --- .vale/config/vocabularies/Nephio/accept.txt | 40 ++++++++++++++++++--- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 9a53c83e..98983ba8 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -7,6 +7,9 @@ apiserver ASN ASNs [Aa]utoscaling +backtrackVal +[Bb]ool +[Bb]oolean cabundle [Cc]onfigmap Codegen @@ -20,16 +23,24 @@ CRs CRD CRDs Crossplane +CSV +deployer Dockerfile Docsy +encodedVal +[Ee]num envtest -[Ee]xecute [Ee]tcd +[Ee]xecute +[Ee]xecution +Expr +func gcloud Gitea GitHub GitLab GitOps +golang Graphviz GRPC GVK @@ -37,7 +48,10 @@ GVKs [Hh]ostname [Hh]omebrew html +http https +JFrog +JSON [Kk]pt [Kk]ptfile kubeadm @@ -46,7 +60,9 @@ kubectl kubelet Kubernetes Kustomization -Kustomize +[Kk]ustomize +kpt fn +kpt-fn Libvirt MacBook MetalLB @@ -66,6 +82,8 @@ Multus mgmt Nginx IdP +[Ii]ntercluster +interdependency OAuth oc OCI @@ -77,35 +95,48 @@ OpenID objectSelector [Pp]arameterization [Pp]ackageVariant +[Pp]ackagerevision +[Pp]ackage[Nn]ames params parameterRef passwordless [Pp]kgserver +pluggable Podman [Pp]orch [Pp]orchctl Postgres PVC PVCs +[Rr]emoveKeys +[Rp]epositorySelector +repoTest +[Rr]ebase [Rr]pkg -rootsync +[Rr]oot[Ss]ync +[Rr]ollout SDK starlark stdout stderr [Ss]udo -[Ss]ubpackages +[Ss]ubpackage +[Sp]pecializer TLS [Tt]riage [Tt]ko [Tt]oolchain [Uu]buntu +userid UI UIs URI URIs +upsertRepo upstreamlock [Uu]ntar +[Uu]tils +validator vCPU VirtualBox VLAN @@ -114,6 +145,7 @@ VM VMs VS Code vSphere +wantErr WebUI xApps YAML From 0980b2afedffcf744fcc64967e66db7a108c2fdf Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Thu, 9 Jan 2025 18:02:37 +0000 Subject: [PATCH 72/74] Pin gh action runner version for linkchecker --- .github/workflows/check-links-md.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/check-links-md.yml b/.github/workflows/check-links-md.yml index d1e40606..7b16a89c 100644 --- a/.github/workflows/check-links-md.yml +++ b/.github/workflows/check-links-md.yml @@ -6,7 +6,7 @@ on: jobs: docs: - runs-on: ubuntu-latest + runs-on: ubuntu-22.04 steps: - name: Check out repository code uses: actions/checkout@v4 From 89f34a4feb3b2c9f0ceb2e20add9029a62ace963 Mon Sep 17 00:00:00 2001 From: Fiachra Corcoran Date: Thu, 9 Jan 2025 18:09:58 +0000 Subject: [PATCH 73/74] Remove redundant prow job --- .prow.yaml | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 .prow.yaml diff --git a/.prow.yaml b/.prow.yaml deleted file mode 100644 index d20a60cb..00000000 --- a/.prow.yaml +++ /dev/null @@ -1,13 +0,0 @@ -presubmits: - - name: env-test-sample-prow-job - decorate: true - always_run: true - spec: - containers: - - image: golang:1.20.2 - command: - - "/bin/sh" - args: - - "-c" - - | - env From 3b8da7aec476d42047eeeed3d9bde2f769e278ab Mon Sep 17 00:00:00 2001 From: Dominika Schweier Date: Thu, 9 Jan 2025 11:27:06 +0100 Subject: [PATCH 74/74] Correcting errors found by Vale Signed-off-by: Dominika Schweier --- .vale/config/vocabularies/Nephio/accept.txt | 11 +++++++++-- .../docs/guides/install-guides/common-dependencies.md | 2 +- .../guides/install-guides/explore-nephio-free5gc.md | 2 +- .../en/docs/guides/install-guides/install-on-byoc.md | 6 +++--- .../guides/install-guides/install-on-multiple-vm.md | 4 ++-- .../guides/install-guides/install-on-openshift.md | 8 ++++---- .../en/docs/guides/install-guides/web-ui/_index.md | 8 ++++---- .../guides/install-guides/web-ui/webui-auth-gcp.md | 8 ++++---- .../guides/install-guides/web-ui/webui-auth-okta.md | 4 ++-- 9 files changed, 30 insertions(+), 23 deletions(-) diff --git a/.vale/config/vocabularies/Nephio/accept.txt b/.vale/config/vocabularies/Nephio/accept.txt index 98983ba8..c7cee35c 100644 --- a/.vale/config/vocabularies/Nephio/accept.txt +++ b/.vale/config/vocabularies/Nephio/accept.txt @@ -1,4 +1,5 @@ # Accepted words (other acronyms must be explained) +amfName Ansible Anthos API @@ -6,6 +7,7 @@ APIs apiserver ASN ASNs +authProvider [Aa]utoscaling backtrackVal [Bb]ool @@ -48,8 +50,8 @@ GVKs [Hh]ostname [Hh]omebrew html -http -https +HTTP +HTTPS JFrog JSON [Kk]pt @@ -70,6 +72,7 @@ MetalLB Nephio nerdctl Netlify +networkName NF NFDeploy NFDeployment @@ -115,12 +118,14 @@ repoTest [Rr]pkg [Rr]oot[Ss]ync [Rr]ollout +sbi SDK starlark stdout stderr [Ss]udo [Ss]ubpackage +SSH [Sp]pecializer TLS [Tt]riage @@ -135,6 +140,7 @@ URIs upsertRepo upstreamlock [Uu]ntar +[Uu]ndeploy [Uu]tils validator vCPU @@ -148,6 +154,7 @@ vSphere wantErr WebUI xApps +XXFDeployment YAML # Nephio contributors mentioned in the docs diff --git a/content/en/docs/guides/install-guides/common-dependencies.md b/content/en/docs/guides/install-guides/common-dependencies.md index 722a15d5..594a4924 100644 --- a/content/en/docs/guides/install-guides/common-dependencies.md +++ b/content/en/docs/guides/install-guides/common-dependencies.md @@ -12,7 +12,7 @@ installation, the CRDs that come along with them are necessary. {{% alert title="Note" color="primary" %}} -If you want to use a version other than that of v3.0.0 of Nephio *catalog* repo, then replace the *@origin/v3.0.0* +If you want to use a version other than that of v3.0.0 of Nephio *catalog* repository, then replace the *@origin/v3.0.0* suffix on the package URLs on the `kpt pkg get` commands below with the tag/branch of the version you wish to use. While using KPT you can [either pull a branch or a tag](https://kpt.dev/book/03-packages/01-getting-a-package) from a diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md index ad95da9e..f91784d6 100644 --- a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md +++ b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md @@ -56,7 +56,7 @@ tasks such as * createService: This function creates a Service resource for the AMF deployment. It defines the desired state of the service, including the selector for the associated deployment and the ports it exposes. * createConfigMap: This function creates a ConfigMap resource for the AMF deployment. It generates the - configuration data for the AMF based on the provided template values and renders it into the amfcfg.yaml file. + configuration data for the AMF based on the provided template values and renders it into the *amfcfg.yaml* file. * createResourceRequirements: This function calculates the resource requirements (CPU and memory limits and requests) for the AMF deployment based on the specified capacity and sets them in a ResourceRequirements object. * createNetworkAttachmentDefinitionNetworks: This function creates the network attachment definition networks for diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md index 2643f3c2..6c9ddd2f 100644 --- a/content/en/docs/guides/install-guides/install-on-byoc.md +++ b/content/en/docs/guides/install-guides/install-on-byoc.md @@ -22,7 +22,7 @@ your environment and choices. - *kpt* [installed](https://kpt.dev/installation/kpt-cli) on your workstation (version v1.0.0-beta.43 or later) - *porchctl* [installed](/content/en/docs/porch/user-guides/porchctl-cli-guide.md) on your workstation - - Sudo-less *docker*, *podman*, or *nerdctl*. If using *podman* or *nerdctl*, + - Sudo-less *docker*, *Podman*, or *nerdctl*. If using *Podman* or *nerdctl*, you must set the [`KPT_FN_RUNTIME`](https://kpt.dev/reference/cli/fn/render/?id=environment-variables) environment variable. @@ -125,9 +125,9 @@ If you wish to avoid running `kubectl port-forward`, the use of Kubernetes Ingre ### Nephio WebUI Authentication and Authorization In the default configuration, the Nephio WebUI **is wide open with no -authentication**. The webui itself authenticates to the cluster using a static +authentication**. The WebUI itself authenticates to the cluster using a static service account, which is bound to the cluster admin role. Any user accessing -the webui is **acting as a cluster admin**. +the WebUI is **acting as a cluster admin**. This configuration is designed for **testing and development only**. You must not use this configuration in any other situation, and even for testing and diff --git a/content/en/docs/guides/install-guides/install-on-multiple-vm.md b/content/en/docs/guides/install-guides/install-on-multiple-vm.md index f70440a6..00b1c587 100644 --- a/content/en/docs/guides/install-guides/install-on-multiple-vm.md +++ b/content/en/docs/guides/install-guides/install-on-multiple-vm.md @@ -54,7 +54,7 @@ If you want to use GitHub or GitLab then follow below steps Get a [GitHub token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) if your repository is private, to allow Porch to make modifications. -Register the edge repository using *kpt* cli or Nephio WebUI. +Register the edge repository using *kpt* CLI or Nephio WebUI. ```bash GITHUB_USERNAME= @@ -82,7 +82,7 @@ kpt live apply --reconcile-timeout=15m --output=table {{% alert title="Note" color="primary" %}} * For management cluster you have to name the repository as *mgmt*. -* In the *repository* package by default gitea address is *172.18.0.200:3000* in *repository/set-values.yaml* +* In the *repository* package by default Gitea address is *172.18.0.200:3000* in *repository/set-values.yaml* change this to your git address. * *repository/token-configsync.yaml* and *repository/token-porch.yaml* are responsible for creating secrets with the help of Nephio token controller for accessing git instance for root-sync. You would need the name of config-sync token diff --git a/content/en/docs/guides/install-guides/install-on-openshift.md b/content/en/docs/guides/install-guides/install-on-openshift.md index 3e0a5789..52f5ffc4 100644 --- a/content/en/docs/guides/install-guides/install-on-openshift.md +++ b/content/en/docs/guides/install-guides/install-on-openshift.md @@ -25,7 +25,7 @@ In this guide, you will set up Nephio with: ## Prerequisites - A Red Hat Account and access to https://console.redhat.com/openshift/ -- OpenShift cli client *oc*. [Download here](https://console.redhat.com/openshift/downloads) +- OpenShift CLI client *oc*. [Download here](https://console.redhat.com/openshift/downloads) ## Setup the Management Cluster @@ -58,12 +58,12 @@ Once installed, you need to prepare the management cluster for zero touch provis If using init.sh directly to deploy Nephio management components, as one would for a generic K8s Cluster, there are some prerequisites to consider: - A default StorageClass must be configured providing persistent storage for PVCs (for instance through the LVMS Operator and an LVMCluster) -- [Security Context Constraits](https://github.com/nephio-project/catalog/tree/main/distros/openshift/security-context-constraints) must be applied for successful Nephio component deployment +- [Security Context Constraints](https://github.com/nephio-project/catalog/tree/main/distros/openshift/security-context-constraints) must be applied for successful Nephio component deployment -Follow the steps present in the [Install Guide](/content/en/docs/guides/install-guides/_index.md) for a Pre-installed K8s Cluster to install manaement components +Follow the steps present in the [Install Guide](/content/en/docs/guides/install-guides/_index.md) for a Pre-installed K8s Cluster to install management components -### Option 2: Using Blueprints Nephio OpenShift Repo OpenShift Package Repository +### Option 2: Using Blueprints Nephio OpenShift Repository OpenShift Package Repository A repository of OpenShift-installation specific packages must be used to deploy Nephio. This repository contains packages derived from the standard Nephio R1 packages, but with OpenShift-specific modifications. diff --git a/content/en/docs/guides/install-guides/web-ui/_index.md b/content/en/docs/guides/install-guides/web-ui/_index.md index 3c61ca1b..d25c8a90 100644 --- a/content/en/docs/guides/install-guides/web-ui/_index.md +++ b/content/en/docs/guides/install-guides/web-ui/_index.md @@ -13,12 +13,12 @@ kpt pkg get --for-deployment https://github.com/nephio-project/nephio-packages.g Before we apply it to the cluster, however, we should configure it. -By default, it expects the webui to be reached via *http://localhost:7007*. If you plan to expose the webui via a load +By default, it expects the WebUI to be reached via *http://localhost:7007*. If you plan to expose the WebUI via a load balancer service instead, then you need to configure the scheme, hostname, port, and service. Note that if you wish to use HTTPS, you should set the *scheme* to *https*, but you will need to terminate the TLS at the load balancer as the container currently only supports HTTP. -This information is captured in the application ConfigMap for the webui, which is generated by a KRM function. We can +This information is captured in the application ConfigMap for the WebUI, which is generated by a KRM function. We can change the values in the *nephio-webui/gen-configmap.yaml* just using a text editor (change the *hostname* and *port* values under *params:*), and those will take effect later when we run `kpt fn render`. As an alternative to a text editor, you can run these commands: @@ -36,8 +36,8 @@ or run: kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-kind Service -- 'by-path=spec.type' 'put-value=LoadBalancer' ``` -In the default configuration, the Nephio WebUI **is wide open with no authentication**. The webui itself authenticates to -the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the webui is +In the default configuration, the Nephio WebUI **is wide open with no authentication**. The WebUI itself authenticates to +the cluster using a static service account, which is bound to the cluster admin role. Any user accessing the WebUI is **acting as a cluster admin**. This configuration is designed for **testing and development only**. You must not use this configuration in any other diff --git a/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md b/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md index 31814237..e97ed61f 100644 --- a/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md +++ b/content/en/docs/guides/install-guides/web-ui/webui-auth-gcp.md @@ -10,7 +10,7 @@ weight: 7 When used with the WebUI running in a GKE cluster, the users authorization roles will be automatically synchronized based upon their IAM roles in GCP. -If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you +If you are not exposing the WebUI on a load balancer IP address, but are instead using `kubectl port-forward`, you should use *http*, *localhost* and *7007* for the SCHEME, HOSTNAME and PORT; otherwise, use the scheme, DNS name and port as it will be seen by your browser. You can leave the port off if it is 443 for HTTPS or 80 for HTTP. @@ -25,7 +25,7 @@ client ID and secret: 4. Click **Create Credentials** and choose **OAuth client ID** 5. Configure an OAuth consent screen, if required - - For scopes, select *openid*, *auth/userinfo.email*, *auth/userinfo.profile*, and *auth/cloud-platform*. + - For scopes, select *OpenID*, *auth/userinfo.email*, *auth/userinfo.profile*, and *auth/cloud-platform*. - Add any users that will want access to the UI if using External user type 6. Set **Application Type** to *Web Application* with these settings: @@ -49,7 +49,7 @@ kubectl create secret generic -n nephio-webui nephio-google-oauth-client --from- ## Enable Google OAuth -The *webui* package has a function that will configure the package for authentication with different services. Edit the +The *WebUI* package has a function that will configure the package for authentication with different services. Edit the *set-auth.yaml* file to set the authProvider field to *google* or run the following command: ```bash @@ -57,7 +57,7 @@ kpt fn eval nephio-webui --image gcr.io/kpt-fn/search-replace:v0.2.0 --match-nam ``` ## Enable OIDC with Google -The *webui* package has a function that will configure the package for authentication with different services. Edit the +The *WebUI* package has a function that will configure the package for authentication with different services. Edit the *set-auth.yaml* file to set the authProvider field to *oidc* and the oidcTokenProvider to *google*, or run the following commands: diff --git a/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md b/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md index 85610448..bdd067e7 100644 --- a/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md +++ b/content/en/docs/guides/install-guides/web-ui/webui-auth-okta.md @@ -5,7 +5,7 @@ description: > weight: 7 --- -If you are not exposing the webui on a load balancer IP address, but are instead using `kubectl port-forward`, you +If you are not exposing the WebUI on a load balancer IP address, but are instead using `kubectl port-forward`, you should use *localhost* and *7007* for the HOSTNAME and PORT; otherwise, use the DNS name and port as it will be seen by your browser. @@ -60,7 +60,7 @@ kubectl create secret generic -n nephio-webui nephio-okta-oauth-client \ ## Enable the WebUI Auth Provider -The *webui* package has a function that will configure the package for authentication with different services. Edit the +The *WebUI* package has a function that will configure the package for authentication with different services. Edit the *set-auth.yaml* file to set the authProvider field to *oidc* and the oidcTokenProvider to *okta*, or run the following commands: