Tutorial showing how to set up a local Porch server towards a Kind cl…

…uster
Nordix · Feb 28, 2024 · 80f2886 · 80f2886
1 parent 7b222d5
commit 80f2886
Show file tree

Hide file tree

Showing 4 changed files with 249 additions and 1 deletion.
diff --git a/docs/tutorials/porch-development-environment/README.md b/docs/tutorials/porch-development-environment/README.md
@@ -0,0 +1,151 @@
+# Setting up a development environment for Porch
+
+This tutorial gives short instructions on how to set up a development environment for Porch. 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.
+
+# Setup kind with MetalLB and Gitea
+
+Follow steps 1-5 inclusive of the [Starting with Porch](https://github.com/nephio-project/porch/tree/main/docs/tutorials/starting-with-porch) tutorial. You now have 2 Kind clusters
+running with Gitea installed. Gitea has the repositories `management` and `edge1` defined.
+
+> **_NOTE:_** The [setup script](bin/setup.sh) automates steps 1-5 of the Starting with Porch tutorial. You may need to adaot this script to your local environment.
+
+> **_NOTE:_** The [cleardown script script](bin/cleardown.sh) clears everything down by deleting the `management` and `edge1` Kind clusters. USE WITH CARE.
+
+
+You can reach the Gitea web interface on the address reported byt he following command:
+```
+kubectl get svc -n gitea gitea        
+NAME    TYPE           CLUSTER-IP      EXTERNAL-IP      PORT(S)                       AGE
+gitea   LoadBalancer   10.197.10.118   172.18.255.200   22:31260/TCP,3000:31012/TCP   8m35s
+```
+
+# Install the Porch function runner
+
+The Porch server requires that the Porch function runner is executing. To install the Porch function runner on the Kind management cluster, execute the following commands.
+
+```
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/0-packagerevs.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/0-packagevariants.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/0-packagevariantsets.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/0-repositories.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/1-namespace.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/catalog/main/nephio/core/porch/2-function-runner.yaml
+
+kubectl wait --namespace porch-system \
+                --for=condition=ready pod \
+                --selector=app=function-runner \
+                --timeout=300s
+```
+
+The Porch function runner should now be executing
+
+```
+kubectl get pod -n porch-system --selector=app=function-runner
+NAME                              READY   STATUS    RESTARTS   AGE
+function-runner-67d4c7c7b-7wm97   1/1     Running   0          16m
+function-runner-67d4c7c7b-czvvq   1/1     Running   0          16m
+```
+
+Expose the `function-runner` service so that the Porch server running in Visual Studio Code can reach it, change the service type from `ClusterIP` to `LoadBalancer`:
+
+```
+kubectl edit svc -n porch-system function-runner
+
+31c31
+<   type: ClusterIP
+---
+>   type: LoadBalancer
+```
+
+Now check that the `function-runner` service has been assigned an IP address external to the cluster:
+```
+kubectl get svc -n porch-system function-runner
+NAME              TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)          AGE
+function-runner   LoadBalancer   10.197.168.148   172.18.255.201   9445:31794/TCP   22m
+```
+
+# Install Porch resources for standalone execution
+
+The Porch server requires that the following resources are defined int he K8S cluster where it is executed:
+
+- The `porch-system` namespace, an API Service called `apiservice.apiregistration.k8s.io/v1alpha1.porch.kpt.dev` and the `service.api` service to expose the API Service. These resources are defined in the the file `deployments/local/localconfig.yaml`
+- the `repositories.config.porch.kpt.dev` and `functions.config.porch.kpt.dev` CRDs. These CRDs are defined in the `api/porchconfig/v1alpha1/` directory.
+- the `packagerevs.config.porch.kpt.dev` CRD. This CRD is defined in the `internal/api/porchinternal/v1alpha1/` directory.
+- 
+
+```
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/main/deployments/local/localconfig.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/main/api/porchconfig/v1alpha1/config.porch.kpt.dev_repositories.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/main/api/porchconfig/v1alpha1/config.porch.kpt.dev_functions.yaml
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/main/internal/api/porchinternal/v1alpha1/config.porch.kpt.dev_packagerevs.yaml
+```
+Verify that the resources have been created
+```
+kubectl api-resources | grep -i porch
+functions                                      config.porch.kpt.dev/v1alpha1     true         Function
+packagerevs                                    config.porch.kpt.dev/v1alpha1     true         PackageRev
+packagevariants                                config.porch.kpt.dev/v1alpha1     true         PackageVariant
+packagevariantsets                             config.porch.kpt.dev/v1alpha2     true         PackageVariantSet
+repositories                                   config.porch.kpt.dev/v1alpha1     true         Repository
+```
+
+# Configure VSCode to run the Porch server
+
+Check out porch and start vscode in the root of your checked out Porch repo.
+
+Edit your local `.vscode.launch.json` file as follows:
+1. Change the `--kubeconfig` value to point at your local Kind cluster configuration file
+2. Change the `--function-runner` IP address to that of the function runner service running in the Kind `management` cluster
+
+```
+        {
+            "name": "Launch Server",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${workspaceFolder}/cmd/porch/main.go",
+            "args": [
+                "--secure-port=9443",
+                "--v=7",
+                "--standalone-debug-mode",
+                "--kubeconfig=/home/sean-citizen/.kube/kind-management-config",
+                "--cache-directory=${workspaceFolder}/.cache",
+                "--function-runner=172.18.255.201:9445"
+            ],
+            "env": {
+				"KUBECONFIG": "/Users/liam/.kube/kind-management-config"
+			},
+            "cwd": "${workspaceFolder}"
+        },
+```
+
+You can now launch the Porch server locally in VSCode by selecting the "Launch Server" configuration on the VSCode "Run and Debug" window.
+
+# Create Repositories using your local Porch server
+
+Follow step 6 to connect Gitea to Porch in the [Starting with Porch](https://github.com/nephio-project/porch/tree/main/docs/tutorials/starting-with-porch#connect-the-gitea-repositories-to-porch) tutorial to create the Gitea and external repositories in Porch.
+
+You will notice logging messages in VSCode when you run the command `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.
+
+```
+porchctl repo get -A
+NAME                  TYPE   CONTENT   DEPLOYMENT   READY   ADDRESS
+edge1                 git    Package   true         True    http://172.18.255.200:3000/nephio/edge1.git
+external-blueprints   git    Package   false        True    https://github.com/nephio-project/free5gc-packages.git
+management            git    Package   false        True    http://172.18.255.200:3000/nephio/management.git
+```
+
+You can also check the repositories using kubectl.
+
+```
+kubectl get  repositories -n porch-demo  
+NAME                  TYPE   CONTENT   DEPLOYMENT   READY   ADDRESS
+edge1                 git    Package   true         True    http://172.18.255.200:3000/nephio/edge1.git
+external-blueprints   git    Package   false        True    https://github.com/nephio-project/free5gc-packages.git
+management            git    Package   false        True    http://172.18.255.200:3000/nephio/management.git
+```
+
+You now have a locally running Porch server. Happy developing!
diff --git a/docs/tutorials/porch-development-environment/bin/cleardown.sh b/docs/tutorials/porch-development-environment/bin/cleardown.sh
@@ -0,0 +1,7 @@
+#! /bin/bash
+
+kind delete cluster --name management
+kind delete cluster --name edge1
+
+rm ~/.kube/kind-management-config
+rm ~/.kube/kind-edge1-config
diff --git a/docs/tutorials/porch-development-environment/bin/setup.sh b/docs/tutorials/porch-development-environment/bin/setup.sh
@@ -0,0 +1,90 @@
+#! /bin/bash
+
+os_type=$(uname)
+if [ "$os_type" = "Darwin" ]
+then
+  SED="gsed"
+else
+  SED="sed"
+fi
+
+# Create mgmt and edge1 clusters in kind
+curl -s https://raw.githubusercontent.com/nephio-project/porch/main/docs/tutorials/starting-with-porch/kind_management_cluster.yaml | \
+  kind create cluster --config=-
+
+curl -s https://raw.githubusercontent.com/nephio-project/porch/main/docs/tutorials/starting-with-porch/kind_edge1_cluster.yaml | \
+  kind create cluster --config=-
+
+kind get kubeconfig --name=management > ~/.kube/kind-management-config
+kind get kubeconfig --name=edge1 > ~/.kube/kind-edge1-config
+
+export KUBECONFIG=~/.kube/kind-management-config
+
+# Instal MetalLB
+kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.12/config/manifests/metallb-native.yaml
+kubectl wait --namespace metallb-system \
+                --for=condition=ready pod \
+                --selector=component=controller \
+                --timeout=90s
+
+kubectl apply -f https://raw.githubusercontent.com/nephio-project/porch/main/docs/tutorials/starting-with-porch/metallb-conf.yaml
+
+TMP_DIR=$(mktemp -d)
+
+pushd "$TMP_DIR" || exit
+
+mkdir kpt_packages
+pushd kpt_packages || exit
+
+# Install Gitea
+kpt pkg get https://github.com/nephio-project/catalog/tree/main/distros/sandbox/gitea
+$SED -i 's/ metallb.universe.tf/ #metallb.universe.tf/' gitea/service-gitea.yaml
+kpt fn render gitea
+kpt live init gitea
+kpt live apply gitea
+
+popd || exit
+
+# Create management and edge1 repos in gitea
+curl -k -H "content-type: application/json" "http://nephio:[email protected]:3000/api/v1/user/repos" --data '{"name":"management"}'
+curl -k -H "content-type: application/json" "http://nephio:[email protected]:3000/api/v1/user/repos" --data '{"name":"edge1"}'
+
+mkdir repos
+pushd repos || exit
+
+# Initialize management and edge1 repos in Gitea
+git clone http://172.18.255.200:3000/nephio/management
+pushd management || exit
+
+touch README.md
+git init
+git checkout -b main
+git config user.name nephio
+git add README.md
+
+git commit -m "first commit"
+git remote remove origin
+git remote add origin http://nephio:[email protected]:3000/nephio/management.git
+git remote -v
+git push -u origin main
+popd || exit
+
+git clone http://172.18.255.200:3000/nephio/edge1
+pushd edge1 || exit
+
+touch README.md
+git init
+git checkout -b main
+git config user.name nephio
+git add README.md
+
+git commit -m "first commit"
+git remote remove origin
+git remote add origin http://nephio:[email protected]:3000/nephio/edge1.git
+git remote -v
+git push -u origin main
+popd || exit
+
+popd || exit
+
+rm -fr "$TMP_DIR"
diff --git a/docs/tutorials/starting-with-porch/README.md b/docs/tutorials/starting-with-porch/README.md
@@ -1,4 +1,4 @@
-# Porch Tutorial
+# Starting with Porch Tutorial
 
 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 with `git`, `docker`, and `kubernetes`.