How to get started with Symbiosis and Kubernetes


# Creating a Kubernetes Cluster

This quickstart will walk you through the process of setting up a Kubernetes cluster with Symbiosis and connecting to `kubectl` from your command line.

To set-up your own cluster first [sign-in](https://app.symbiosis.host/signin) to access your team console.

## 1. Configuration

We begin by navigating to the **Add new** section under **Kubernetes Clusters**.

Beside selecting the name and version of your cluster you will also be prompted to configure your node pools.

## 2. Node Pools

Node pools define groups of nodes that run workloads inside your clusters. A node is in essence a virtual machine that runs a set of Kubernetes services that communicate with your Kubernetes control plane.

If you allocate too few or too small nodes you may risk running out of resources, in order to prevent downtime you can configure autoscaling that will automatically size your cluster up or down as usage fluctuates.

## 3. Provision

Selecting high-availability (HA) means that Symbiosis will spawn multiple control plane replicas to safeguard against a single control plane being unavailable. We strongly recommend using HA clusters for clusters running critical workloads.

When you have created your cluster you will be redirected to the cluster view. Now it's time to connect to our cluster using standard Kubernetes tooling.

## 4. Kubectl

kubectl is a command-line tool used to run commands against your Kubernetes cluster. You can use kubectl to deploy applications, inspect and manage cluster resources, view logs and much more.

Instructions on how to install can be found for [Windows](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/), [OSX](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/) and [Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).

## 5. Creating a user account

In the Symbiosis UI navigate to the **User Account** tab and create a user account for yourself.

Having a user account lets you download the config file that is used by kubectl and various other tools to connect to your cluster.

## 6. Installing the kubeconfig file

Click the **Download** button on your new account.

By default, kubectl looks for a config in `~/.kube/config`. Create the `.kube` directory if it doesn't exist and add the config.

The below command will optionally merge with any pre-existing config and select your new cluster as the default context. Substitute `<CONFIG>` with the path to the downloaded config file.

```bash
$ mkdir -p ~/.kube && KUBECONFIG=<CONFIG>:~/.kube/config kubectl config view --flatten > ~/.kube/config
```

## 7. Verify that everything works

Let's verify to make sure the cluster has been set up correctly.

```bash
$ kubectl get nodes
NAME               STATUS   ROLES    AGE   VERSION
general-1-feqtck   Ready    <none>   23h   v1.23.5
general-1-lbgyqx   Ready    <none>   23h   v1.23.5
```

Voila! You're ready to start using your cluster.

## Next steps

If you prefer using a GUI to manage Kubernetes have a look at [Lens](https://k8slens.dev). For a TUI we are happy users of [k9s](https://k9scli.io/).

Now that you have a cluster ready you're all set to launch your first container, see [Deploying a container](/docs/quickstart/deploying-a-container).


Get started by setting up your first Kubernetes cluster in Symbiosis

Creating a Cluster


# Deploying a Container

In Kubernetes the most basic building block is the Pod.

In many ways a Pod resembles something like running docker-compose; it contains one or more containers with configurable ports, networking, environment variables and more.

In very few cases will you need to create a Pod yourself. Instead Kubernetes defines a few different resources that in turn will manage your pods for you.

## Workload Resources

- **Deployment** - Ensures a desired number of pod replicas are running simultaneously
- **StatefulSet** - Used for stateful applications where pods need access to persistent storage
- **DaemonSet** - Manages sets of pods so that all (or some) nodes each run at least one replica
- **Job** - Creates one or more pods that retry until a specified number of them succeed
- **CronJob** - Schedules one or more pods to run on a timer

For a typical stateless application running multiple replicas you will probably want to use a Deployment. In this how-to we will go through how to use Deployments to launch a container and access it over the internet.

## 1. Publishing your Docker Image

How to build a docker image is out of scope for this article. However, in order for you cluster to be able to access your image it will have to be available in a docker registry.

Docker maintains their own registry that can be used to publish public images freely. If you don't want them to be globally available you have to pay.

However, it's also possible (and pretty easy) to launch your own docker registry into your own cluster. [Harbor](https://goharbor.io/) and [Docker Registry](https://docs.docker.com/registry/) are two such alternatives.

## 2. Image Pull Secret

We will need to provide a way for Kubernetes to authenticate against your protected registry. You can skip this step if your images are public.

Fill in the details below to create a docker-registry secret named my-registry-cred that we can use for authentication in the following step.

```
kubectl create secret docker-registry my-registry-cred \
  --docker-server=<your-registry-server> \
  --docker-username=<your-name> \
  --docker-password=<your-password> \
  --docker-email=<your-email>
```

## 3. Create a Deployment

We will create a simple deployment with three replicas running an image named `docker-registry/my-backend-api`.

By default Kubernetes uses a rolling update strategy. This means that, for example, if we update the image tag it will roll out the new pods one by one to avoid any potential downtime.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-backend-api
  labels:
    app: my-backend-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-backend-api
  template:
    metadata:
      labels:
        app: my-backend-api
    spec:
      containers:
        - name: my-backend-api
          image: docker-registry/my-backend-api
          ports:
            - containerPort: 80
      imagePullSecrets: # Can be omitted if your images are public!
        - name: my-registry-cred
```

When we have created and saved our manifest we can apply it to our cluster.

```shell
kubectl create -f deploy.yaml
```

Voila! Your container should now be running, check its status by writing `kubectl describe pod my-backend-api`.

## 4. Accessing your app from the Internet

However, your container will not be accessible from the internet. If you want to enable an ingress have a look at installing an ingress controller such as [NGINX Ingress](https://kubernetes.github.io/ingress-nginx/deploy/).

## 5. What's next

For more information on Kubernetes Deployments have a look at the [official documentation](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/).


Build and launch a docker container to your Kubernetes cluster

Deploying a Container


# Using the CLI tool

`sym` is a command-line utility that allows you to easily manage your Symbiosis resources.
With the CLI tool you can make daily operations easier and integrate Symbiosis into your
CI/CD workflows.

### <Image alt="Mac logo" width="18" height="18" src="/images/apple.png" /> Homebrew (Mac OSX)

If you have Homebrew installed, you can install the Symbiosis CLI by running:

```shell
brew install symbiosis-cloud/tap/sym
```

If you don't have Homebrew installed you can also use the installer script:

```shell
curl -s https://raw.githubusercontent.com/symbiosis-cloud/cli/main/install.sh | sh
```

### <Image alt="Linux logo" width="18" height="18" src="/images/linux.png" /> Linux

Run the CLI installation script by issuing the following command.

```shell
curl -s https://raw.githubusercontent.com/symbiosis-cloud/cli/main/install.sh | sh
```

The installer may prompt for sudo rights in order to install the binary.

### <Image alt="Windows logo" width="18" height="18" src="/images/windows.png" /> Windows

We currently do not have an installer for Windows. However, binaries for Windows can be downloaded from our [GitHub releases](https://github.com/symbiosis-cloud/cli/releases).

## Authentication

The CLI offers two options for authentication, signing in through the web UI or by using an API key.

You can log in using your own access token by issuing the following command:

```shell
sym login
```

You will be prompted to login to Symbiosis using your browser.

Alternatively, you can also authenticate the CLI using an API key:

```shell
sym config init <api key>
```

You can generate a suitable API key [from the web UI](https://app.symbiosis.host/api-keys).

## Listing clusters

```shell
sym cluster list

ID                                    NAME                VERSION
b568c426-6fab-41ce-8313-4e7284af52eb  my-prod-cluster     1.24.4
21c5e526-8f8d-4483-9506-b658e924709c  my-staging-cluster  1.24.4
```

You can change the output format of commands by using the `-o` flag to print the output in json or yaml format.

```shell
$ sym cluster describe -o json my-prod-cluster
{
  "id": b568c426-6fab-41ce-8313-4e7284af52eb,
  "name": "my-prod-cluster",
  ...
}
```

## Creating a Cluster

With our CLI you can easily create new clusters and get started with them right away.

Let's create a simple autoscaling cluster with two to four general-2 nodes.

**Note** The `--merge` flag installs the kube context of the new cluster so it can be used for kubectl and other local tools (issuing `--merge` will require confirmation).

```shell
sym cluster create my-cluster --autoscaling --min-nodes=2 --max-nodes=4 -t general-2 --merge

ID                                    NAME        VERSION  NODE TYPE  # NODES
af558bb8-8f86-4c4f-8c80-136d56667b61  my-cluster  1.24.4   general-2        2
```

You can see all available flags by running `sym cluster create --help`

The kubeconfig file can also be exported or installed manually:

```shell
# output the kubeconfig to stdout
sym cluster identity my-cluster

# output the kubeconfig to a specific file
sym cluster identity my-cluster -i /path/to/file

# Install the kubeconfig into your existing .kube/config
sym cluster identity my-cluster --merge
```

In order to delete the cluster you can run:

```shell
sym cluster delete my-cluster
```

## Adding a node pool to an existing cluster

To add a new node-pool to an existing cluster you can issue the following command:

```shell
sym node-pool create new-pool my-cluster -n 1 -t general-1

ID                                    NAME      TYPE       QUANTITY
224e3ce9-142f-4434-999d-329c05ad992f  new-pool  general-1         1
```

### Creating an autoscaling node-pool

The following command can be used to create a node-pool that scales automatically between 1 and 5 nodes:

```shell
sym node-pool create new-pool my-cluster --autoscaling --min-nodes 1 --max-nodes 5 1 -t general-1

ID                                    NAME      TYPE       QUANTITY
224e3ce9-142f-4434-999d-329c05ad992f  new-pool  general-1         1
```


Manage your cloud resources with our developer friendly CLI

Using the CLI

Getting started


# Control Planes

With Symbiosis your Kubernetes control plane is fully managed and free of charge.

## High-availability (HA)

An unreachable control plane can be problematic for business critical applications that rely on an always accessible API server. For example, while running pods will continue to operate workloads configured with an Horizontal Pod Autoscaler will only scale when the control plane is accessible. It's therefore important to plan for how to keep your applications running if worst comes to worst.

At Symbiosis a cluster can be configured for high availability (HA). With HA your control plane will be managed by multiple replicas that can protect against downtime in case of single-node failures and disruptions.

HA can also increase responsiveness of your API-server by distributing your load. This is most noticeable for read-only requests since updates don't need to be consolidated among the replicas.

## Version upgrades

Symbiosis will automatically update the patch version of your Kubernetes cluster with non-breaking changes.

Symbiosis supports a set of three consecutive minor versions. If your cluster version falls behind our set of supported versions we will force an update. Keeping our users on recent and supported versions helps reduce exposure to security vulnerabilities and makes it easier for us to provide adequate support.

During an update, the control plane with controllers and data store are upgraded to the new version. Your workloads will not be impacted during the upgrade.

After control planes are upgraded Symbiosis will begin replacing your pools with nodes of the new version. Symbiosis will spawn additional nodes in order to avoid any downtime, this means that for a period after an upgrade your pools will contain more billable nodes than requested.


Learn how your control planes are used to manage your Kubernetes clusters

Control Planes


# Nodes

A Kubernetes node is a virtual machine capable of running Kubernetes workloads. Node pools can easily be provisioned for your cluster through the Web UI or [Terraform](/docs/how-to/terraform).

## Hostpath volumes

Nodes should be regarded as ephemeral as the node disk is wiped during cluster upgrades. Therefore you should avoid using hostpath volumes whenever possible. Note that this doesn't impact [PVC provisioned volumes](/docs/features/volumes), which is the recommended way to provision storage.

## Node types

All nodes run on modern AMD processors. As the cores are shared the nodes can be scheduled to run more efficiently which allows us to offer much lower prices at comparable performance for the average use case.

## Networking

Nodes are configured with one NAT interface for internet traffic, and one VXLAN interface for inter-node traffic. Only egress traffic over the NAT interface will count towards your nodes monthly traffic allotment. We currently don't offer any support for fixed outbound addresses or per-node publicly routable IP addresses.

## Usable memory

Part of the memory and CPU allocation of each node is required for critical processes and daemons such as init system, kubelet, CSI- and CNI daemons. Under normal operation these services will reserve around ~400MiB of memory, meaning that a 2vCPU/4GiB node will have around 3700MiB of usable memory.

## Security

We use a [zero trust security model](https://en.wikipedia.org/wiki/Zero_trust_security_model). All nodes communicate with api-servers over mutual TLS with Symbiosis handling the distribution, signing and renewal of node and control plane certificates.

Node images are automatically encrypted on rest using LUKS.


Create pools of node to handle your workloads

Nodes


# Object Storage

**Object Storage is currently in a closed beta. Join our Discord to request access.**

## What is it?


Simple, scalable and affordable s3-compatible object storage.

Object Storage


# Symbiosis Projects

**Projects is in early preview so expect that some things might not work as intended. Please let us know what you think of Projects and reach out if you have any issues!**

## What is it?

Projects hooks up your code repos to your k8s environment.

Projects hooks up your code repos to your cloud environment to get automatic access to a bunch of nice features.

- Ephemeral dev environments
- Preview environments with preview URLs
- CI - Automatic end-to-end tests on any pull request
- CD - Deploy changes to live environments

This is automatically configured for you by integrating our GitHub app and configuring your helm charts, tests and variables in the `sym.yaml` file.

With Projects we want to make it dead simple to develop, test and release on Kubernetes. Say goodbye to separate docker-compose files and convoluted CI/CD pipelines to get your development and integration-testing done right.

### Use-cases

### The `sym.yaml` file

```yaml
# sym.yaml
deploy:
  helm:
    - name: hello-world
      chart: ./charts/hello-world
      values:
        nameOverride: { { Secret "example" } }
test:
  - image: backend:latest
    command: go test
```

Examples are available on [GitHub](https://github.com/symbiosis-cloud/examples).

## Limitations & known issues

- Preview URLs are not implemented yet
- Kustomize isn't supported yet

Hot reloading is not supported yet. We recommend plugging in [Skaffold](https://skaffold.dev/) to develop in real-time on your Symbiosis environments.


Projects


# Volumes

Volumes offer persistent storage for your Kubernetes cluster. Volumes are created by defining [Persistent Volume Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) (PVCs) in Kubernetes. Using PVCs allows nodes to read and write logs, database records, store metrics and enables many other use-cases that require persistent storage.

Volumes are automatically encrypted on rest with LUKS.

### Notes

The _minimum_ billable amount for storage volumes is 1GiB.

Symbiosis currently supports volumes up to 1 TiB, if you need larger volumes please [contact us](mailto:info@symbiosis.host).

## Creating a PVC

Below is an example manifest to create a volume that can later be mounted to a pod:

```yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi # amount of storage to be requested
  storageClassName: symbiosis-block-storage # this line can be omitted as symbiosis-block-storage is the default CSI driver
  volumeMode: Filesystem
```

You can read more about persistent volumes and how they can be configured in the [official documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/).

## Creating a StatefulSet with a PVC

Unlike [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/), a StatefulSet ensures each pod has access to its own volume such that no two pods mount the same volume.

A possible manifest for deploying a postgres database with a 64GiB volume could look like this:

```yaml
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  labels:
    app: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:14
          env:
            - name: POSTGRES_PASSWORD
              value: password
          ports:
            - containerPort: 5432
              name: postgresdb
          volumeMounts:
            - name: postgres-pvc
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:
    - metadata:
        name: postgres-pvc
      spec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 64Gi
```

This configuration will look for a PVC named `postgres-pvc`, if none is found a new PVC is created. The name of a PVC can only contain lowercase alphanumerical characters and dashes, PVC names need to be unique for each cluster.

Symbiosis only supports the `ReadWriteOnce` access mode, meaning that the PVC can only be bound to one node at a time. For more info on access modes see the [official documentation](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes).

Volumes are billed by the minute, starting when the PVC is initially created. To end billing, the PVC needs to be deleted. You can see a list of all volumes in the Web UI by browsing to the specific cluster.


Create persistent volumes for databases, object storage or other stateful applications

Volumes

Features

Learn the different ways you can use Symbiosis


# Launching a Postgres database

**Symbiosis currently doesn't offer managed databases. Instead, we suggest using a Kubernetes operator to manage the database for you.**

[CloudNativePG](https://cloudnative-pg.io/) is an operator for creating low-maintenance and production-ready Postgres clusters in Kububernetes. CloudNativePG supports with operations such as:

- Replication
- Automatic point-in-time backups
- Built-in monitoring
- Rolling updates

This page will show you how to install CloudNativePG and how you can launch a highly available Postgres with just a short and sweet custom resource.

CloudNativePG offers a wide range of features and options that we do not cover in this article, but you can find it in their [official documentation](https://cloudnative-pg.io/documentation/1.19/).

## Installation

Install the CloudNativePG operator and custom resource definitions using Helm:

```bash
helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg
```

## Creating a Postgres cluster

Once the helm chart is installed, create a Postgres database with the below manifest:

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: example-postgres
  namespace: default
spec:
  instances: 3
  storage:
    size: 10Gi
```

This will provision a primary database with two read-replicas, each with 10GiB persistent storage.

## Accessing your cluster

CloudNativePG will create a database called `app` by default, with credentials to access the database stored in the secret `<CLUSTER_NAME>-app`.

Four different services are created to connect to postgres:

- `<CLUSTER_NAME>-any` - load balances between all postgres DBs in the clusters (both read and writeable)
- `<CLUSTER_NAME>-r` - selects all readable instances
- `<CLUSTER_NAME>-rw` - selects all read and writeable instances
- `<CLUSTER_NAME>-ro` - selects instances that are only readable, but not writeable

These services are not publicly exposed, i.e they are only accessible within your k8s cluster.

You can then launch Pgweb, a minimal Web UI for accessing Postgres, by creating a deployment that uses the read-write services with the credentials stored in `example-cluster-app`:

```
apiVersion: apps/v1
kind: Deployment
metadata:
  name: pgweb
  labels:
    app: pgweb
spec:
  replicas: 1
  selector:
    matchLabels:
      app: pgweb
  template:
    metadata:
      labels:
        app: pgweb
    spec:
      containers:
      - name: pgweb
        image: sosedoff/pgweb
        ports:
        - containerPort: 8081
        env:
        - name: PSQL_USERNAME
          valueFrom:
            secretKeyRef:
              name: example-postgres-app
              key: username
        - name: PSQL_PASSWORD
          valueFrom:
            secretKeyRef:
              name: example-postgres-app
              key: password
        - name: DATABASE_URL
          value: postgres://$(PSQL_USERNAME):$(PSQL_PASSWORD)@example-postgres-rw:5432/app?sslmode=disable
```

We can access the UI by port-forwarding to the pod, since it doesn't have an Ingress or LoadBalancer configured:

```bash
kubectl port-forward deployment/pgweb 8081:8081
```

The interface should now be visible at `localhost:8081` and connected to your newly created postgres cluster.

Voilà! We've set up a highly-available Postgres cluster and connected to the primary DB using the provided credentials.

## Monitoring

If you are using the [Kube prometheus stack](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack) in your cluster you can easily export Postgres metrics:

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgresql-storage-class
spec:
  [...]
  monitoring:
    enablePodMonitor: true
```

The generated `PodMonitor` will pull IO, transaction, storage and other various data directly into your prometheus instance.

## Backups

CloudNativePG can be configured to store PIT (point-in-time) backups to various different sinks.

Backups require that you have s3-compatible storage, for example by launching a Minio instance into your cluster.

Configure backups with your access key and storage key:

```yaml
apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgresql-storage-class
spec:
  backup:
    barmanObjectStore:
      destinationPath: "<destination path here>"
      s3Credentials:
        accessKeyId:
          name: aws-creds
          key: ACCESS_KEY_ID
        secretAccessKey:
          name: aws-creds
          key: ACCESS_SECRET_KEY
```

Backups can be scheduled by creating a `ScheduledBackup` resource that points to your cluster. The below configuration will create a backup every midnight UTC.

```
apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
  name: backup-example
spec:
  schedule: "0 0 0 * * *"
  backupOwnerReference: self
  cluster:
    name: example-cluster
```

See their [official documentation](https://cloudnative-pg.io/documentation/1.19/bootstrap/#bootstrap-from-a-backup-recovery) for how to restore your cluster from a backup.

## Alternative operators

CloudNativePG is a simple operator for running a production-ready Postgres database. However, there are many other alternatives, like these ones below:

- [Zalando Postgres Operator](https://github.com/zalando/postgres-operator)
- [Crunchy Postgres Operator](https://www.crunchydata.com/products/crunchy-postgresql-for-kubernetes)
- [KubeDB](https://kubedb.com/)
- [Percona Operator for PostgreSQL](https://docs.percona.com/percona-operator-for-postgresql/index.html)


Launch highly available DBs with automatic backups, prometheus monitoring, rolling upgrades and more

Launching a Postgres database


# Horizontal Pod Autoscaler (HPA)

This guide will help you set up a Horizontal Pod Autoscaler (HPA) in your cluster.

In short, A Horizontal Pod Autoscaler can automatically scale the amount of replicas for your deployments, stateful sets or other workloads.

Scaling can be configured based on metrics like CPU or Memory. When the metric(s) that you wish to use (for example CPU usage) exceeds your defined thresholds the HPA will automatically scale your workload up. Should the average utilisation drop the HPA will scale your workload down again.

You can find more information about what an HPA is and how it works [here](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).

## Installing the Kubernetes Metrics Server

In order to use an HPA you will need to enable the Kubernetes Metrics Server, for example using Helm or kubectl.

An HPA uses the Metrics Server in order to track metrics for your pods that are used to make scaling decisions.

### 1) Installation via kubectl

Run the following kubectl command in your cluster in order to install the Metrics Server.

```
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml
```

### 2) Installation via Helm

Run the following Helm commands to install the Metrics Server onto your Kubernetes cluster:

```
helm repo add metrics-server https://kubernetes-sigs.github.io/metrics-server/
helm repo update metrics-server
helm upgrade --install metrics-server metrics-server/metrics-server
```

## Creating your Horizontal Pod Autoscaler

In order for us to test if the HPA will work we will need to create a sample deployment:

```
cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: php-apache
spec:
  selector:
    matchLabels:
      run: php-apache
  replicas: 1
  template:
    metadata:
      labels:
        run: php-apache
    spec:
      containers:
      - name: php-apache
        image: registry.k8s.io/hpa-example
        ports:
        - containerPort: 80
        resources:
          limits:
            cpu: 500m
          requests:
            cpu: 200m
EOF
```

Now you can create a simple HPA as such:

```
kubectl autoscale deployment php-apache --cpu-percent=50 --min=1 --max=10
```

This will create an HPA for the php-apache deployment. It will scale up when the average CPU usage of your pods exceeds 50% up to 10 pods total.

The resulting HPA will look like this:

```
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: php-apache
  namespace: default
spec:
  maxReplicas: 10
  metrics:
  - resource:
      name: cpu
      target:
        averageUtilization: 50
        type: Utilization
    type: Resource
  minReplicas: 1
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: php-apache
```

If the targets show up correctly as x%/50% then it means that the HPA works as intended and the Metrics Server returns a valid value.

```
kubectl get hpa -w

NAME         REFERENCE               TARGETS         MINPODS   MAXPODS   REPLICAS   AGE
php-apache   Deployment/php-apache   <unknown>/50%   1         10        0          7s
php-apache   Deployment/php-apache   0%/50%          1         10        1          15s
```

You can check out a more thorough example on the official Kubernetes documentation section about [Horizontal Pod Autoscaling](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough/).


Scale the number of pod replicas based on metrics like CPU and memory usage

Using Horizontal Pod Autoscalers


# Pulumi

Pulumi is a infrastructure-as-code tool for managing infrastructure in one of several supported
programming languages. Pulumi can be used to automatically provision, update
and decomission your Symbiosis resources.

The Symbiosis provider supports Pulumi for Typescript/Javascript, C#, Go, Python and YAML.

## Installing Pulumi

In order to install pulumi you need to both install the command line tool and also the packages necessary for your language of choice.

Lets start by installing the CLI:

<CodeDocs groupId="os">
  <CodeDocs.TabItem tabId="osx">
```bash
brew install pulumi/tap/pulumi
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="linux">
```bash
curl -fsSL https://get.pulumi.com | sh
```
  </CodeDocs.TabItem>
</CodeDocs>

Verify that the CLI was installed correctly:
```bash
pulumi version
```

## Bootstrapping a Pulumi project

With the CLI installed we can proceed by creating a new project for our configuration files.

First, lets create the directory and change into it:

```bash
mkdir symbiosis-pulumi
cd symbiosis-pulumi
```

Next, lets use the CLI to scaffold a new project using our language of choice.

<CodeDocs groupId="pulumi">
  <CodeDocs.TabItem tabId="typescript">
```bash
pulumi new typescript -y
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="python">
```bash
pulumi new python -y
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="golang">
```bash
pulumi new go -y
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="csharp">
```bash
pulumi new csharp -y
```
  </CodeDocs.TabItem>
</CodeDocs>

Pulumi should now have populated the directory with the files necessary to run.
However it will not contain any configuration.

## Configuring a Symbiosis cluster

Now that we have the project ready we can proceed to define the resource that we want Pulumi to manage. So, next up we need to install the Symbiosis plugin:

<CodeDocs groupId="pulumi">
  <CodeDocs.TabItem tabId="typescript">
```bash
# For NPM
npm install @symbiosis-cloud/symbiosis-pulumi
# ... or Yarn
yarn add @symbiosis-cloud/symbiosis-pulumi
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="python">
```bash
pip install symbiosis-pulumi
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="golang">
```bash
go get github.com/symbiosis-cloud/pulumi-symbiosis/sdk/go/...
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="csharp">
```bash
dotnet add package Symbiosis.Pulumi.Symbiosis
```
  </CodeDocs.TabItem>
</CodeDocs>

With the plugin install we can proceed by opening the core entrypoint (depending on language, ie. `index.ts` for typescript). Replace with these lines in order to define a cluster and node pool.

<CodeDocs groupId="pulumi">
  <CodeDocs.TabItem tabId="typescript">
```typescript
import * as pulumi from "@pulumi/pulumi";
import * as symbiosis from "@symbiosis-cloud/symbiosis-pulumi";

const cluster = new symbiosis.Cluster("my-cluster", {
    region: "germany-1"
});

const nodePool = new symbiosis.NodePool("my-pool-1", {
    cluster: cluster.name,
    nodeType: "general-1",
    quantity: 3,
});

export const kubeconfig = cluster.kubeconfig;
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="python">
```python
import symbiosis_pulumi as symbiosis

cluster = symbiosis.Cluster("my-cluster", region="germany-1")

example_node_pool = symbiosis.NodePool("my-pool-1",
    cluster=cluster.name,
    node_type="general-1",
    quantity=3)

pulumi.export("kubeconfig", cluster.kubeconfig)
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="golang">
```go
package main

import (
	"github.com/pulumi/pulumi/sdk/v3/go/pulumi"
	"github.com/symbiosis-cloud/pulumi-symbiosis/sdk/go/symbiosis"
)

func main() {
	pulumi.Run(func(ctx *pulumi.Context) error {
		cluster, err := symbiosis.NewCluster(ctx, "my-cluster", &symbiosis.ClusterArgs{
			Region: pulumi.String("germany-1"),
		})
		if err != nil {
			return err
		}
		_, err = symbiosis.NewNodePool(ctx, "my-pool-1", &symbiosis.NodePoolArgs{
			Cluster:  cluster.Name,
			NodeType: pulumi.String("general-1"),
			Quantity: pulumi.Int(3),
		})
		if err != nil {
			return err
		}
    ctx.Export("kubeconfig", cluster.Kubeconfig)
		return nil
	})
}
```
  </CodeDocs.TabItem>
  <CodeDocs.TabItem tabId="csharp">
```csharp
using System.Collections.Generic;
using Pulumi;
using Symbiosis = Symbiosis.Pulumi.Symbiosis;

return await Deployment.RunAsync(() => 
{
    var cluster = new Symbiosis.Cluster("my-cluster", new()
    {
        Region = "germany-1",
    });

    var nodePool = new Symbiosis.NodePool("my-pool-1", new()
    {
        Cluster = cluster.Name,
        NodeType = "general-1",
        Quantity = 3,
    });

    return new Dictionary<string, object>
    {
        ["kubeconfig"] = cluster.Kubeconfig,
    };
});
```
  </CodeDocs.TabItem>
</CodeDocs>

These steps instruct Pulumi to allocate a new cluster named `my-cluster` and attach a node pool with 3 nodes of type `general-1` and export the kubeconfig variable we will need to connect to the cluster later on. The [API docs](https://www.pulumi.com/registry/packages/symbiosis/api-docs/) list all possible arguments that can be passed for both cluster and node pool, such as autoscaling configuration.

Next step is to configure our Symbiosis API Key, they can be generated from the API Keys tab in the UI, by API or by CLI.

```bash
pulumi config set symbiosis:apiKey MY_API_KEY
```

## Provisioning the cluster

Now we're ready to deploy our cluster. Pulumi will generate a plan for how to achieve the desired state. As this is a first deploy Pulumi will only prompt for the creation of your new cluster and not modify or delete any existing resources. In order to proceed Pulumi will ask for your confirmation:

```bash
$ pulumi up
Previewing update (dev)

     Type                         Name              Plan
     pulumi:pulumi:Stack          symbiosis-pulumi
 +   ├─ symbiosis:index:Cluster   my-cluster        create
 +   └─ symbiosis:index:NodePool  my-pool-1         create


Outputs:
  + kubeconfig: output<string>

Resources:
    + 2 to create
    1 unchanged

Do you want to perform this update?
> yes
  no
  details
```

After the cluster is initialized we can use the output variable to export the kubeconfig necessary to access the cluster:

```bash
pulumi stack output kubeconfig --show-secrets >config
```

Verify that the config works properly:

```bash
$ KUBECONFIG=config kubectl get nodes
```

The config can be placed in `~/.kube/config` to be automatically picked up by tools such as `kubectl`.

## Next steps

Pulumi can also be used to provision your Kubernetes deployments, services or other resources. Have a look into [their registry](https://www.pulumi.com/registry/) to identify which parts of your infrastructure can be provisioned in Pulumi.

Further reading:
- [Deploying a stateless application to Kubernetes](https://www.pulumi.com/registry/packages/kubernetes/how-to-guides/stateless-app/) (Pulumi How-to)
- [Symbiosis plugin repository](https://github.com/symbiosis-cloud/pulumi-symbiosis)
- [Symbiosis plugin docs](https://www.pulumi.com/registry/packages/symbiosis/api-docs/)


Configure your environments in your programming language of choice

Infrastructure-as-code with Pulumi


# Terraform

Terraform is a declarative tool for building and maintaining infrastructure, like your clusters and node pools on Symbiosis.

This guide will show how to setup a cluster using terraform.

For a complete reference of the Symbiosis terraform provider see the [official documentation](https://registry.terraform.io/providers/symbiosis-cloud/symbiosis/latest/docs).

## Installing terraform

Terraform is a command line tool. Links to download Terraform can be found [here](https://www.terraform.io/downloads).

Ensure that terraform is properly installed:

```bash
which terraform
```

## Generate API Key

In order for terraform to be able to create and delete clusters on your behalf it must have a valid Symbiosis API Key.

API Keys can be created through the [Web UI](https://app.symbiosis.host/) under `auth & membership` → `api keys`.

## Creating a Cluster

Create the following file and name it `main.tf`.

```
terraform {
  required_providers {
    symbiosis = {
      source = "symbiosis-cloud/symbiosis"
      version = ">= 0.3"
    }
  }
}

variable "symbiosis_api_key" {}

provider "symbiosis" {
  api_key = var.symbiosis_api_key
}

resource "symbiosis_cluster" "staging" {
  name = "production-cluster"
  region = "germany-1"
}

resource "symbiosis_node_pool" "general" {
  cluster = symbiosis_cluster.staging.name
  name = "general-pool"
  node_type = "general-1"
  quantity = 2
}

resource "symbiosis_node_pool" "cpu" {
  cluster = symbiosis_cluster.staging.name
  name = "cpu-pool"
  node_type = "memory-3"
  quantity = 4
}
```

The manifest will provision one Kubernetes cluster with two node pools, one pool with two general purpose nodes and another pool with four memory optimized nodes. For a list of all node types see section on [Nodes](/reference/nodes).

To create the cluster issue the following command:

```bash
terraform apply --var "symbiosis_api_key=<YOUR API KEY>"
```

Terraform will output a diff showing the new resources that will be created, make sure the diff aligns with your expectations before proceeding. If any future changes are made issuing the same above command will update the configuration.

The terraform state will be stored locally as no backend has been defined. It's considered best practice (and especially useful if you work with others) to define a remote backend, see [the terraform documentation](https://www.terraform.io/language/settings/backends).


Neatly structure your Kubernetes infrastructure using our Terraform plugin

Manage clusters with Terraform


# Load Balancers

Creating a Kubernetes Service of type `LoadBalancer` will provision an external Symbiosis load balancer for your cluster, balancing the requests among all worker nodes. A public IPv4 address will be assigned to each load balancer.

## Creating a Load Balancer

Creating a load balancer is as easy as defining a Service with type `LoadBalancer`, see example below:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  selector:
    app: my-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: LoadBalancer
```

The above service will balance traffic between pods with the label `app: my-app` on port 8080.

Once the load balancer is bound the IP address can be retrieved with `kubectl`:

```
kubectl get svc my-service --output jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

Billing will start as soon as the load balancer is created and will be billed by the minute until it has been deleted.

## UDP load balancing

Currently Symbiosis does not support UDP load balancing.


Enable external access to your containers by using load balancers and ingresses

Configuring Load Balancers

How to

More on Symbiosis and what we are building


# Security

This document outlines a few of the security measures we take as a company in order to keep your cloud resources safe and information on how to report any suspected abuse or vulnerabilities.

## Symbiosis Infrastructure

Hardening our infrastructure means measures aimed at reducing the attack surface of our services and ensure only authenticated and authorized parties can access private resources in our cloud.

- Platform networking runs over VXLAN overlay networks
- Communication between applications and servers secured behind mTLS
- Data centers equipped with DDOS mitigation
- Data in storage and volumes are encrypted with LUKS block encryption with centrally stored secrets
- Remote management is fully audited; remote access is done using short-lived cert-based SSH sessions
- Nodes are virtualized using Libvirt (KVM), battle tested and widely used for over 15 years

## Development (DevSec)

DevSec (Development Security) groups the measures we take to ensure we can build, release and maintain our software in a secure and robust manner.

- Access to are internal services is gated using a SSO Identity Provider
- Proposed changes to our core services are verified with code reviews, automated E2E-testing, integration testing and unit testing
- Services are written in memory-safe, robust and battle tested languages and frameworks (including Golang, Kotlin, Spring Boot)

## Abuse

We take abuse complaints seriously. Please report any suspect activity to abuse@symbiosis.host.

## Vulnerability Reporting

We appreciate all efforts from our users to identify and remedy any potential vulnerabilities in our system.

If you would like to report a vulnerability in one our services please email security@symbiosis.host and include the steps to reproduce including any relevant information concerning tools and versions used.


Our security principles for development and infrastructure

Documentation

Installation

Tutorials