Development process

After you ran the setup script as explained in the environment setup you are ready to start the actual development of porch. That process involves (among others) a combination of the tasks explained below.

Build and deploy all of porch

The following command will rebuild all of porch and deploy all of its components into your porch-test kind cluster (created in the environment setup):

make run-in-kind

Troubleshoot the porch API server

There are several ways to develop, test and troubleshoot the porch API server. In this chapter we describe an option where every other parts of porch is running in the porch-test kind cluster, but the porch API server is running locally on your machine, typically in an IDE.

The following command will rebuild and deploy porch, except the porch API server component, and also prepares your environment for connecting the local API server with the in-cluster components.

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 VS Code to run the Porch (API)server

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.

2. 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. 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.

Check to ensure that the API server is serving requests:

curl https://localhost:4443/apis/porch.kpt.dev/v1alpha1 -k

{
  "kind": "APIResourceList",
  "apiVersion": "v1",
  "groupVersion": "porch.kpt.dev/v1alpha1",
  "resources": [
    {
      "name": "packagerevisionresources",
      "singularName": "",
      "namespaced": true,
      "kind": "PackageRevisionResources",
      "verbs": [
        "get",
        "list",
        "patch",
        "update"
      ]
    },
    {
      "name": "packagerevisions",
      "singularName": "",
      "namespaced": true,
      "kind": "PackageRevision",
      "verbs": [
        "create",
        "delete",
        "get",
        "list",
        "patch",
        "update",
        "watch"
      ]
    },
    {
      "name": "packagerevisions/approval",
      "singularName": "",
      "namespaced": true,
      "kind": "PackageRevision",
      "verbs": [
        "get",
        "patch",
        "update"
      ]
    },
    {
      "name": "packages",
      "singularName": "",
      "namespaced": true,
      "kind": "Package",
      "verbs": [
        "create",
        "delete",
        "get",
        "list",
        "patch",
        "update"
      ]
    }
  ]
}

Troubleshoot the porch controllers

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:

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 file of the porch git repo.

Run the unit tests

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:

make test-e2e

To run the end-to-end tests against a clean deployment, issue:

make test-e2e-clean

This will

• create a brand new kind cluster,
• rebuild porch
• deploy the newly built porch into the new cluster
• run the end-to-end tests against that
• deletes the kind cluster if all tests passed

This process closely mimics the end-to-end tests that are run against your PR on Github.

In order to run just one particular test case you can execute something similar to this:

E2E=1 go test -v ./test/e2e -run TestE2E/PorchSuite/TestPackageRevisionInMultipleNamespaces

or this:

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.

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:

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.

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).

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.

Getting to know the make targets

Try: make help

Restart with a clean-slate

Sometimes the development kind cluster gets cluttered and you may experience weird behavior from porch. In this case you might want to restart with a clean slate: First, delete the development kind cluster with the following command:

kind delete cluster --name porch-test

then re-run the setup script:

./scripts/setup-dev-env.sh

finally deploy porch into the kind cluster by any of the methods explained above.