How to get involved

• 1: Advice for new contributors
• 2: Writing code
• 3: Writing documentation
• 4: Troubleshooting

1 - Advice for new contributors

This page contains more general advice on ways you can contribute to SpinKube, and how to approach that.

If you are looking for a reference on the details of making code contributions, see the Writing code documentation.

First steps

Start with these steps to be successful as a contributor to SpinKube.

Join the conversation

It can be argued that collaboration and communication are the most crucial aspects of open source development. Gaining consensus on the direction of the project, and that your work is aligned with that direction, is key to getting your work accepted. This is why it is important to join the conversation early and often.

To join the conversation, visit the #spinkube channel on the CNCF Slack.

Read the documentation

The SpinKube documentation is a great place to start. It contains information on how to get started with the project, how to contribute, and how to use the project. The documentation is also a great place to find information on the project’s architecture and design.

SpinKube’s documentation is great but it is not perfect. If you find something that is unclear or incorrect, please submit a pull request to fix it. See the guide on writing documentation for more information.

Triage issues

If an issue reports a bug, try and reproduce it. If you can reproduce it and it seems valid, make a note that you confirmed the bug. Make sure the issue is labeled properly. If you cannot reproduce the bug, ask the reporter for more information.

Write tests

Consider writing a test for the bug’s behavior, even if you don’t fix the bug itself.

issues labeled good first issue are a great place to start. These issues are specifically tagged as being good for new contributors to work on.

Guidelines

As a newcomer on a large project, it’s easy to experience frustration. Here’s some advice to make your work on SpinKube more useful and rewarding.

Pick a subject area that you care about, that you are familiar with, or that you want to learn about

You don’t already have to be an expert on the area you want to work on; you become an expert through your ongoing contributions to the code.

Start small

It’s easier to get feedback on a little issue than on a big one, especially as a new contributor; the maintainters are more likely to have time to review a small change.

If you’re going to engage in a big task, make sure that your idea has support first

This means getting someone else to confirm that a bug is real before you fix the issue, and ensuring that there’s consensus on a proposed feature before you go implementing it.

Be bold! Leave feedback!

Sometimes it can be scary to put your opinion out to the world and say “this issue is correct” or “this patch needs work”, but it’s the only way the project moves forward. The contributions of the broad SpinKube community ultimately have a much greater impact than that of any one person. We can’t do it without you!

Err on the side of caution when marking things ready for review

If you’re really not certain if a pull request is ready for review, don’t mark it as such. Leave a comment instead, letting others know your thoughts. If you’re mostly certain, but not completely certain, you might also try asking on Slack to see if someone else can confirm your suspicions.

Wait for feedback, and respond to feedback that you receive

Focus on one or two issues, see them through from start to finish, and repeat. The shotgun approach of taking on lots of issues and letting some fall by the wayside ends up doing more harm than good.

Be rigorous

When we say “this pull request must have documentation and tests”, we mean it. If a patch doesn’t have documentation and tests, there had better be a good reason. Arguments like “I couldn’t find any existing tests of this feature” don’t carry much weight; while it may be true, that means you have the extra-important job of writing the very first tests for that feature, not that you get a pass from writing tests altogether.

Be patient

It’s not always easy for your issue or your patch to be reviewed quickly. This isn’t personal. There are a lot of issues and pull requests to get through.

Keeping your patch up to date is important. Review the pull request on GitHub to ensure that you’ve addressed all review comments.

2 - Writing code

Interested in giving back to the community a little? Maybe you’ve found a bug in SpinKube that you’d like to see fixed, or maybe there’s a small feature you want added.

Contributing back to SpinKube itself is the best way to see your own concerns addressed. This may seem daunting at first, but it’s a well-traveled path with documentation, tooling, and a community to support you. We’ll walk you through the entire process, so you can learn by example.

Who’s this tutorial for?

For this tutorial, we expect that you have at least a basic understanding of how SpinKube works. This means you should be comfortable going through the existing tutorials on deploying your first app to SpinKube. It is also worthwhile learning a bit of Rust, since many of SpinKube’s projects are written in Rust. If you don’t, Learn Rust is a great place to start.

Those of you who are unfamiliar with git and GitHub will find that this tutorial and its links include just enough information to get started. However, you’ll probably want to read some more about these different tools if you plan on contributing to SpinKube regularly.

For the most part though, this tutorial tries to explain as much as possible, so that it can be of use to the widest audience.

Code of Conduct

As a contributor, you can help us keep the SpinKube community open and inclusive. Please read and follow our Code of Conduct.

Install git

For this tutorial, you’ll need Git installed to download the current development version of SpinKube and to generate a branch for the changes you make.

To check whether or not you have Git installed, enter git into the command line. If you get messages saying that this command could not be found, you’ll have to download and install it. See Git’s download page for more information.

If you’re not that familiar with Git, you can always find out more about its commands (once it’s installed) by typing git help into the command line.

Fork the repository

SpinKube is hosted on GitHub, and you’ll need a GitHub account to contribute. If you don’t have one, you can sign up for free at GitHub.

SpinKube’s repositories are organized under the spinkube GitHub organization. Once you have an account, fork one of the repositories by visiting the repository’s page and clicking “Fork” in the upper right corner.

Then, from the command line, clone your fork of the repository. For example, if you forked the spin-operator repository, you would run:

git clone https://github.com/YOUR-USERNAME/spin-operator.git

Read the README

Each repository in the SpinKube organization has a README file that explains what the project does and how to get started. This is a great place to start, as it will give you an overview of the project and how to run the test suite.

Run the test suite

When contributing to a project, it’s very important that your code changes don’t introduce bugs. One way to check that the project still works after you make your changes is by running the project’s test suite. If all the tests still pass, then you can be reasonably sure that your changes work and haven’t broken other parts of the project. If you’ve never run the project’s test suite before, it’s a good idea to run it once beforehand to get familiar with its output.

Most projects have a command to run the test suite. This is usually something like make test or cargo test. Check the project’s README file for instructions on how to run the test suite. If you’re not sure, you can always ask for help in the #spinkube channel on Slack.

Find an issue to work on

If you’re not sure where to start, you can look for issues labeled good first issue in the repository you’re interested in. These issues are often much simpler in nature and specifically tagged as being good for new contributors to work on.

Create a branch

Before making any changes, create a new branch for the issue:

git checkout -b issue-123

Choose any name that you want for the branch. issue-123 is an example. All changes made in this branch will be specific to the issue and won’t affect the main copy of the code that we cloned earlier.

Write some tests for your issue

If you’re fixing a bug, write a test (or multiple tests) that reproduces the bug. If you’re adding a new feature, write a test that verifies the feature works as expected. This will help ensure that your changes work as expected and don’t break other parts of the project.

Confirm the tests fail

Now that we’ve written a test, we need to confirm that it fails. This is important because it verifies that the test is actually testing what we think it is. If the test passes, then it’s not actually testing the issue we’re trying to fix.

To run the test suite, refer to the project’s README or reach out on Slack.

Make the changes

Now that we have a failing test, we can make the changes to the code to fix the issue. This is the fun part! Use your favorite text editor to make the changes.

Confirm the tests pass

After making the changes, run the test suite again to confirm that the tests pass. If the tests pass, then you can be reasonably sure that your changes work as expected.

Once you’ve verified that your changes and test are working correctly, it’s a good idea to run the entire test suite to verify that your change hasn’t introduced any bugs into other areas of the project. While successfully passing the entire test suite doesn’t guarantee your code is bug free, it does help identify many bugs and regressions that might otherwise go unnoticed.

Commit your changes

Once you’ve made your changes and confirmed that the tests pass, commit your changes to your branch:

git add .
git commit -m "Fix issue 123"

Push your changes

Now that you’ve committed your changes to your branch, push your branch to your fork on GitHub:

git push origin issue-123

Create a pull request

Once you’ve pushed your changes to your fork on GitHub, you can create a pull request. This is a request to merge your changes into the main copy of the code. To create a pull request, visit your fork on GitHub and click the “New pull request” button.

Write documentation

If your changes introduce new features or change existing behavior, it’s important to update the documentation. This helps other contributors understand your changes and how to use them.

See the guide on writing documentation for more information.

Next steps

Congratulations! You’ve made a contribution to SpinKube.

After a pull request has been submitted, it needs to be reviewed by a maintainer. Reach out on the #spinkube channel on the CNCF Slack to ask for a review.

3 - Writing documentation

We place high importance on the consistency and readability of documentation. We treat our documentation like we treat our code: we aim to improve it as often as possible.

Documentation changes generally come in two forms:

1. General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples.
2. New features: documentation of features that have been added to the project since the last release.

This section explains how writers can craft their documentation changes in the most useful and least error-prone ways.

How documentation is written

Though SpinKube’s documentation is intended to be read as HTML at https://spinkube.dev/docs, we edit it as a collection of plain text files written in Markdown for maximum flexibility.

SpinKube’s documentation uses a documentation system known as docsy, which in turn is based on the Hugo web framework. The basic idea is that lightly-formatted plain-text documentation is transformed into HTML through a process known as Static Site Generation (SSG).

Previewing your changes locally

If you want to run your own local Hugo server to preview your changes as you work:

1. Fork the spinkube/documentation repository on GitHub.
2. Clone your fork to your computer.
3. Read the README.md file for instructions on how to build the site from source.
4. Continue with the usual development workflow to edit files, commit them, push changes up to your fork, and create a pull request. If you’re not sure how to do this, see writing code for tips.

Making quick changes

If you’ve just spotted something you’d like to change while using the documentation, the website has a shortcut for you:

1. Click Edit this page in the top right-hand corner of the page.
2. If you don’t already have an up-to-date fork of the project repo, you are prompted to get one - click Fork this repository and propose changes or Update your Fork to get an up-to-date version of the project to edit.

Filing issues

If you’ve found a problem in the documentation, but you’re not sure how to fix it yourself, please file an issue in the documentation repository. You can also file an issue about a specific page by clicking the Create Issue button in the top right-hand corner of the page.

4 - Troubleshooting

The following is a list of common error messages and potential troubleshooting suggestions that might assist you with your work.

SpinKube Support Policy

SpinKube provides support on a best-effort basis. For users who installed SpinKube manually following the documentation, please report issues in the Spin Operator repository. For installations via the Azure Marketplace, please open an issue in the Azure repository for assistance. If your issue is urgent, feel free to raise it in Slack.

Failure downloading the Helm chart

While the Spin Operator Helm chart is public and can be fetched anonymously, you may run into errors pulling the chart if you’ve previously authenticated with the ghcr.io registry but the authentication token has since expired.

The error would look something like the following:

helm install spin-operator \
 --namespace spin-operator --create-namespace --version 0.4.0 --wait oci://ghcr.io/spinkube/charts/spin-operator 
Error: INSTALLATION FAILED: failed to download "oci://ghcr.io/spinkube/charts/spin-operator" at version "0.4.0"

To fix, either re-authenticate with the registry with a valid token (e.g. docker login ghcr.io) or log out of the registry and pull the chart anonymously (e.g. docker logout ghcr.io).

No endpoints available for service “spin-operator-webhook-service”

When following the quickstart guide the following error can occur when running the kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.4.0/spin-operator.shim-executor.yaml command:

Error from server (InternalError): error when creating "https://github.com/spinkube/spin-operator/releases/download/v0.4.0/spin-operator.shim-executor.yaml": Internal error occurred: failed calling webhook "mspinappexecutor.kb.io": failed to call webhook: Post "https://spin-operator-webhook-service.spin-operator.svc:443/mutate-core-spinkube-dev-v1alpha1-spinappexecutor?timeout=10s": no endpoints available for service "spin-operator-webhook-service"

To address the error above, first look to see if Spin Operator is running:

get pods -n spin-operator
NAME                                                READY   STATUS              RESTARTS   AGE
spin-operator-controller-manager-5bdcdf577f-htshb   0/2     ContainerCreating   0          26m

If the above result (ready 0/2) is returned, then use the name from the above result to kubectl describe pod of the spin-operator:

kubectl describe pod spin-operator-controller-manager-5bdcdf577f-htshb -n spin-operator

If the above command’s response includes the message SetUp failed for volume "cert" : secret "webhook-server-cert" not found, please check the certificate. The spin operator requires this certificate to serve webhooks, and the missing certificate could be one reason why the spin operator is failing to start.

The command to check the certificate and the desired output is as follows:

kubectl get certificate -n spin-operator
NAME                         READY   SECRET                AGE
spin-operator-serving-cert   True    webhook-server-cert   11m

Instead of the desired output shown above you may be getting the No resources found in spin-operator namespace. response from the command. For example:

kubectl get certificate -n spin-operator
No resources found in spin-operator namespace.

To resolve this issue, please try to install the Spin Operator again. Except this time, use the helm upgrade --install syntax instead of just helm install:

helm upgrade --install spin-operator \
  --namespace spin-operator \
  --create-namespace \
  --version 0.4.0 \
  --wait \
  oci://ghcr.io/spinkube/charts/spin-operator

Once the Spin Operator is installed you can try and run the kubectl apply -f https://github.com/spinkube/spin-operator/releases/download/v0.4.0/spin-operator.shim-executor.yaml command again. The issue should be resolved now.

Error Validating Data: Connection Refused

When trying to run the kubectl apply -f <URL> command (for example installing the cert-manager etc.) you may encounter an error similar to the following:

$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml

error: error validating "https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml": error validating data: failed to download openapi: Get "https://127.0.0.1:6443/openapi/v2?timeout=32s": dial tcp 127.0.0.1:6443: connect: connection refused; if you choose to ignore these errors, turn validation off with --validate=false

This is because no cluster exists. You can create a cluster following the Quickstart guide.

Installation Failed

When trying to install a new version of a chart you may get the following error:

Error: INSTALLATION FAILED: cannot re-use a name that is still in use

For example, if you have installed v0.14.0 of kwasm-operator using the following helm install command:

helm install \
  kwasm-operator kwasm/kwasm-operator \
  --namespace kwasm \
  --create-namespace \
  --set kwasmOperator.installerImage=ghcr.io/spinkube/containerd-shim-spin/node-installer:v0.14.0

Reissuing the above command with the new version v0.15.0 will result in the following error - Error: INSTALLATION FAILED: cannot re-use a name that is still in use. To use the same command when installing and upgrading a release, use upgrade --install (as referenced here in the official Helm documentation). For example:

helm upgrade --install \
  kwasm-operator kwasm/kwasm-operator \
  --namespace kwasm \
  --create-namespace \
  --set kwasmOperator.installerImage=ghcr.io/spinkube/containerd-shim-spin/node-installer:v0.17.0

Cluster Already Exists

When trying to create a cluster (e.g. a cluster named wasm-cluster) you may receive an error message similar to the following:

FATA[0000] Failed to create cluster 'wasm-cluster' because a cluster with that name already exists

Cluster Information

With k3d installed, you can use the following command to get a cluster list:

$ k3d cluster list
NAME           SERVERS   AGENTS   LOADBALANCER
wasm-cluster   1/1       2/2      true

With `kubectl installed, you can use the following command to dump cluster information (this is much more verbose):

kubectl cluster-info dump

Cluster Delete

With k3d installed, you can delete the cluster by name, as shown in the command below:

$ k3d cluster delete wasm-cluster
INFO[0000] Deleting cluster 'wasm-cluster'
INFO[0002] Deleting cluster network 'k3d-wasm-cluster'
INFO[0002] Deleting 1 attached volumes...
INFO[0002] Removing cluster details from default kubeconfig...
INFO[0002] Removing standalone kubeconfig file (if there is one)...
INFO[0002] Successfully deleted cluster wasm-cluster!

Too long: must have at most 262144 bytes

When running kubectl apply -f my-file.yaml, the following error can occur if the yaml file is too large:

Too long: must have at most 262144 bytes

Using the --server-side=true option resolves this issue:

kubectl apply --server-side=true -f my-file.yaml

Redis Operator

Noted an error when installing Redis Operator:

$ helm repo add redis-operator https://spotahome.github.io/redis-operator
"redis-operator" has been added to your repositories
$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "redis-operator" chart repository
Update Complete. ⎈Happy Helming!⎈
$ helm install redis-operator redis-operator/redis-operator
Error: INSTALLATION FAILED: failed to install CRD crds/databases.spotahome.com_redisfailovers.yaml: error parsing : error converting YAML to JSON: yaml: line 4: did not find expected node content

Used the following commands to enforce using a different version of Redis Operator (whilst waiting on this PR fix to be merged).

$ helm install redis-operator redis-operator/redis-operator --version 3.2.9
NAME: redis-operator
LAST DEPLOYED: Mon Jan 22 12:33:54 2024
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

error: requires go version

When building apps like the cpu-load-gen Spin app, you may get the following error if your TinyGo is not up to date. The error requires go version 1.18 through 1.20 but this is not necessarily the case. It is recommended that you have the latest go installed e.g. 1.21 and downgrading is unnecessary. Instead please go ahead and install the latest version of TinyGo to resolve this error:

user@user:~/spin-operator/apps/cpu-load-gen$ spin build
Building component cpu-load-gen with `tinygo build -target=wasi -gc=leaking -no-debug -o main.wasm main.go`
error: requires go version 1.18 through 1.20, got go1.21