Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Added documentation for creating a local developer environment. #225

Closed
wants to merge 17 commits into from
Closed
Changes from 6 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 51 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope

## Development

### Using GitHub Codespaces
> A [GitHub Codespaces]((https://github.com/features/codespaces)) development flow is described below, which you can use to test Karpenter functionality on your own cluster, and to aid rapid development of this project.

1. **Install VSCode**: Go [here](https://code.visualstudio.com/download) to download VSCode for your platform. After installation, in your VSCode app install the "GitHub Codespaces" Extension. See [here](https://code.visualstudio.com/docs/remote/codespaces) for more information about this extension.
Expand All @@ -22,6 +23,56 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
kubectl scale deployments/inflate --replicas=3
```

### Use local environment instead of GitHub Codespaces.
> Tested environment : WSL2
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should specify distribution, especially since package management is distribution-specific


1. **Install tools**
* make
```bash
sudo apt update && sudo apt install make -y
```
* docker-cli
```bash
curl -fsSL https://get.docker.com | bash -
```
* kubectl
```bash
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" && chmod +x kubectl && sudo mv kubectl /usr/local/bin
```
* [helm](https://github.com/helm/helm/releases)
```bash
curl -L https://get.helm.sh/helm-v3.14.3-linux-amd64.tar.gz | sudo tar xvfz - linux-amd64/helm && sudo mv linux-amd64/helm /usr/local/bin/helm && rm -rf linux-amd64
```
* [golang](https://go.dev/dl/) > 1.21
```bash
curl -L https://go.dev/dl/go1.22.1.linux-amd64.tar.gz | sudo tar xvzf - -C /usr/local/ && PATH=$PATH:/usr/local/go/bin
```
* [yq](https://github.com/mikefarah/yq/releases) / [jq](https://github.com/jqlang/jq/releases)
```bash
sudo apt update && sudo apt install jq -y
curl -Lo yq https://github.com/mikefarah/yq/releases/download/v4.43.1/yq_linux_amd64 && chmod +x yq && sudo mv yq /usr/local/bin
```
* [skaffold](https://skaffold.dev/docs/install/#standalone-binary)
```bash
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/v2.10.1/skaffold-linux-amd64 && chmod +x skaffold && sudo mv skaffold /usr/local/bin
```
* [azure-cli](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
```bash
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
jacobbaek marked this conversation as resolved.
Show resolved Hide resolved
```

2. **Provision cluster, build and deploy Karpenter** : Set `AZURE_SUBSCRIPTION_ID` to your subscription (and customize region in `Makefile-az.mk` if desired). Then run `make az-all`. This logs into Azure (follow the prompts), provisions AKS and ACR (using resource group and cluster name `$COMMON_NAME`, ACR it will not allow dashes), builds and deploys Karpenter, deploys sample `general-purpose` nodepool and `inflate` deployment workload.
```
az config set core.output=json
export AZURE_SUBSCRIPTION_ID=xxxx-xxxx-xxxx-xxxx
export COMMON_NAME=karpenter2test
jacobbaek marked this conversation as resolved.
Show resolved Hide resolved
```

3. Manually scale the `inflate` Deployment workload, watch Karpenter controller log and Nodes in the cluster. Example of manually scaling up to 3 pods:
```
kubectl scale deployments/inflate --replicas=3
Bryce-Soghigian marked this conversation as resolved.
Show resolved Hide resolved
```

### Debugging
To debug Karpenter in-cluster, use `make az-debug`, wait for it to deploy, and attach from VSCode using Start Debugging (F5). After that you should be able to set breakpoints, examine variables, single step, etc. (Behind the scenes, besides building and deploying Karpenter, `skaffold debug` automatically and transparently applies the necessary flags during build, instruments the deployment with Delve, adjusts health probe timeouts - to allow for delays introduced by breakpoints, sets up port-forwarding, etc.; more on how this works is [here](https://skaffold.dev/docs/workflows/debug/).

Expand Down