Skip to content

Latest commit

 

History

History
153 lines (98 loc) · 6.88 KB

local-setup.md

File metadata and controls

153 lines (98 loc) · 6.88 KB
Raw

Preparing the Setup

Conceptually, all Landscaper components are designated to run as a Pod inside a Kubernetes cluster. The Landscaper extends the Kubernetes API by using CRD's that are automatically deployed by the Landscaper controller during startup. If you want to develop it, you may want to work locally with the Landscaper without building a Docker image and deploying it to a cluster each and every time. That means that the Landscaper controller runs outside a Kubernetes cluster which requires providing a Kubeconfig in your local filesystem and point the Landscaper controller to it when starting it (see below).

Deployers are separate controllers that extend the Landscaper and reconcile DeployItems. These Deployers are designed to run as separate controllers in the cluster. However, for development purposes most deployers are included in the Landscaper controller and can be run with the Landscaper controller.

Further details could be found in

  1. Principles of Kubernetes, and its components
  2. Kubernetes Development Guide

This setup is based on k3d. Docker for Desktop, minikube or kind are also supported.

Installing Golang environment

Install latest version of Golang. For MacOS you could use Homebrew:

brew install golang

For other OS, please check Go installation documentation.

⚠️ The Landscaper uses some features that are only available since golang version 1.16. Make sure to use at least golang version 1.16.x.

Installing kubectl and helm

As already mentioned in the introduction, the communication with the Gardener happens via the Kubernetes (Garden) cluster it is targeting. To interact with that cluster, you need to install kubectl. Please make sure that the version of kubectl is at least v1.19.x.

On MacOS run

brew install kubernetes-cli

Please check the kubectl installation documentation for other OS.

The Landscaper and its Deployers are deployed using Helm Charts, so you also need the Helm CLI:

On MacOS run

brew install helm

On other OS please check the Helm installation documentation.

Installing git

We use git as VCS which you need to install.

On MacOS run

brew install git

On other OS, please check the Git installation documentation.

Installing K3d

You'll need to have Docker installed and running.

Follow the k3s installation guide to start a kubernetes cluster.

⚠️ note that with the default k8s cluster installation some development resources like target may not work as on some os's docker is running in VM with different network access. We therefore recommend to use our local setup script in hack/setup-local-env.sh which automatically setups a local environment. In that environment controllers running in- and outside of the cluster can access the apiserver. (Note that this script modifies the /etc/hosts file which may require root permissions)

[MacOS only] Install GNU core utilities

When running on MacOS you have to install the GNU core utilities:

brew install coreutils gnu-sed

This will create symbolic links for the GNU utilities with g prefix in /usr/local/bin, e.g., gsed or gbase64. To allow using them without the g prefix please put /usr/local/opt/coreutils/libexec/gnubin at the beginning of your PATH environment variable, e.g., export PATH=/usr/local/opt/coreutils/libexec/gnubin:$PATH.

[Optional] Installing gcloud SDK

In case you have to create a new release or a new hotfix of the Landscaper you have to push the resulting Docker image into a Docker registry. Currently, we are using the Google Container Registry (this could change in the future). Please follow the official installation instructions from Google.

Local Landscaper setup

Get the sources

Clone the repository from GitHub into your $GOPATH.

mkdir -p $GOPATH/src/github.com/gardener
cd $GOPATH/src/github.com/gardener
git clone git@github.com:gardener/landscaper.git
cd landscaper

Note: Landscaper is using Go modules and cloning the repository into $GOPATH is not a hard requirement. However it is still recommended to clone into $GOPATH because k8s.io/code-generator does not work yet outside of $GOPATH - kubernetes/kubernetes#86753.

Before you start

⚠️ Before you start developing, please have an understanding about the principles of Kubernetes, and its components, what their purpose is and how they interact with each other.

Run the Landscaper

When the Kubernetes cluster is running, start the Landscaper controller with the cluster's kubeconfig. The webhooks for validation, mutation and conversion are not included in the Landscaper binary for scalability and availability reasons. See Run Webhook Server to see how webhooks can be tested.

go run ./cmd/landscaper-controller --kubeconfig=$KUBECONFIG

(Optional) Configure the landscaper controller The Landscaper controller is configured with a configuration file that can be provided via --config flag.

apiVersion: config.landscaper.gardener.cloud/v1alpha1
kind: LandscaperConfiguration

registry:
  oci:
    allowPlainHttp: true # for localhost:5000 clusters
    insecureSkipVerify: true 
    configFiles:
    - "/path/to/docker/auth/config.yaml"

metrics:
  port: 8080
crdManagement:
  deployCrd: true
  forceUpdate: true

Run the Landscaper Webhook Server

The webhooks for validation, mutation and conversion are served by a specific webhook server that can be found in cmd/landscaper-webhooks-server.

It can be simply started with

go run ./cmd/landscaper-webhooks-server --kubeconfig=$KUBECONFIG --port=9443

Note: The webhook server automatically registers the needed webhooks in the k8s cluster using the flags --webhook-service --webhook-service-port which should point to a service that is backed by the webhook server.

Specific webhooks for resources can be disabled using the flag --disable-webhooks=installations,deployitems,...