nephio-project · nephio-prow · Aug 30, 2023 · Aug 17, 2023 · Aug 18, 2023 · Aug 21, 2023
diff --git a/install-guide/README.md b/install-guide/README.md
@@ -171,3 +171,4 @@ ssh <user>@<vm-address>
 * Step through the [exercises](https://github.com/nephio-project/docs/blob/main/user-guide/exercises.md)
 * Learn more about the [Nephio demo sandbox](https://github.com/nephio-project/docs/blob/main/install-guide/explore-sandbox.md)
 * Dig into the [user guide](https://github.com/nephio-project/docs/blob/main/user-guide/README.md)
+* Create a [Bring-Your-Own-Cluster](byoc.md) Nephio Installation
diff --git a/install-guide/byoc.md b/install-guide/byoc.md
@@ -0,0 +1,154 @@
+# Nephio Installation Overview
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Prerequisites](#prerequisites)
+- [Opinionated Installations](#opinionated-installations)
+- [A La Carte Installation](#a-la-carte-installation)
+
+## 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.
+
+## 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)
+ - 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.
+
+## 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.
+
+| Environment | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| [Sandbox](sandbox.md) | The demo sandbox 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 sandbox. These instructions cover both Ubuntu and Fedora. |
+| [Google Cloud Platform](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](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. |
+
+## A 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.
+
+### Git Providers
+
+Nephio can support multiple Git providers for the repositories that contain
+packages. In R1, 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:
+
+| Provider                                                        | Workloads | Provisioning  |
+| --------------------------------------------------------------- | --------- | ------------- |
+| [GitHub](https://github.com)                                    | Yes       | No            |
+| [Gitea](https://about.gitea.com/)                               | Yes       | Yes           |
+| [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.
+
+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 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.
+
+| Provider                    | Notes                                                                                   |
+| --------------------------- | --------------------------------------------------------------------------------------- |
+| [Cluster API](capi.md)      | Kubernetes project cluster provisioner for a variety of cluster providers.              |
+| [KCC](kcc.md)               | Google's Kubernetes Config Connector for GKE clusters and other GCP resources.          |
+| [Crossplane](crossplane.md) | API composition framework with cluster and other infrastructure providers.              |
+
+### Load Balancer
+
+The R1 demo environment uses [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.
+
+### 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*.
+
+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](webui-auth-gcp.md)
+- [OIDC with Okta](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.
+
+You may want to create a package containing those Repository resources, much as
+is done for the sandbox environment.
diff --git a/install-guide/common-components.md b/install-guide/common-components.md
@@ -0,0 +1,73 @@
+# Installing Required Components
+
+*Work-in-Progress*
+
+After installing the environment-specific dependencies, you can install the
+base Nephio components. There are two essential components: Porch, and Nephio
+Controllers.
+
+### 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.
+
+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/nephio-example-packages.git/porch-dev@v1.0.1
+kpt fn render porch-dev
+kpt live init porch-dev
+kpt live apply porch-dev --reconcile-timeout=15m --output=table
+```
+
+### Nephio Controllers
+
+The Nephio Controllers 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 controllers that can provision repositories and bootstrap new clusters into
+Nephio.
+
+To install the Nephio Controllers, repeat the `kpt` steps, but for that package:
+
+```bash
+kpt pkg get --for-deployment https://github.com/nephio-project/nephio-example-packages.git/nephio-controllers@v1.0.1
+kpt fn render nephio-controllers
+kpt live init nephio-controllers
+kpt live apply nephio-controllers --reconcile-timeout=15m --output=table
+```
+
+### Management Cluster GitOps Tool
+
+In the R1 demo environment, a GitOps tool (ConfigSync) is installed to allow
+GitOps-based application of packages to the management cluster itself. This is
+not strictly needed if all you want to do is provision network functions, but it
+is used extensively in the cluster provisioning workflows.
+
+Different GitOps tools may be used, but these intructions 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/nephio-example-packages.git/configsync@v1.0.1
+kpt fn render configsync
+kpt live init configsync
+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.
+
+```bash
+kpt pkg get --for-deployment https://github.com/nephio-project/nephio-example-packages.git/nephio-stock-repos@v1.0.1
+kpt fn render nephio-stock-repos
+kpt live init nephio-stock-repos
+kpt live apply nephio-stock-repos --reconcile-timeout=15m --output=table
+```
diff --git a/install-guide/common-dependencies.md b/install-guide/common-dependencies.md
@@ -0,0 +1,31 @@
+# Common Dependencies
+
+This guide describes how to install some required dependencies that are the
+same across all environments.
+
+Some of these, like the resource-backend, will move out of the "required"
+category in later releases.  Even if you do not use these directly in your
+installation, the CRDs that come along with them are necessary.
+
+### Network Config Operator
+
+This component is a controller for applying configuration to routers and
+switches.
+
+```bash
+kpt pkg get --for-deployment https://github.com/nephio-project/nephio-example-packages.git/network-config@v1.0.1
+kpt fn render network-config
+kpt live init network-config
+kpt live apply network-config --reconcile-timeout=15m --output=table
+```
+
+### Resource Backend
+
+The resource backend provides IP and VLAN allocation.
+
+```bash
+kpt pkg get --for-deployment https://github.com/nephio-project/nephio-example-packages.git/resource-backend@v1.0.1
+kpt fn render resource-backend
+kpt live init resource-backend
+kpt live apply resource-backend --reconcile-timeout=15m --output=table
+```