Unverified Commit fa325201 authored by Konstantinos Tsakalozos's avatar Konstantinos Tsakalozos Committed by GitHub
Browse files

Update README with MicroK8s (#203)

parent 0d1d17ae
# microk8s
# MicroK8s
![](https://img.shields.io/badge/Kubernetes-1.12-326de6.svg)
![](https://img.shields.io/badge/Kubernetes-1.12-326de6.svg) ![Build Status](https://travis-ci.org/ubuntu/microk8s.svg)
<img src="https://raw.githubusercontent.com/cncf/artwork/master/kubernetes/certified-kubernetes/versionless/color/certified-kubernetes-color.png" align="right" width="200px">Kubernetes in a [snap](https://snapcraft.io/) that you can run locally.
## User Guide
Snaps are frequently updated to match each release of Kubernetes. The quickest way to get started is to install directly from the snap store. You can install microk8s and let it update to the latest stable upstream Kubernetes release with:
Snaps are frequently updated to match each release of Kubernetes. The quickest way to get started is to install directly from the snap store. You can install MicroK8s and let it update to the latest stable upstream Kubernetes release with:
```
snap install microk8s --classic
```
Alternatively, you can select a microk8s channel that will follow a specific Kubernetes release series. For example, you install microk8s and let it follow the `v1.12` series with:
Alternatively, you can select a MicroK8s channel that will follow a specific Kubernetes release series. For example, you install MicroK8s and let it follow the `v1.12` series with:
```
snap install microk8s --classic --channel=1.12/stable
```
You can read more on the microk8s release channels in the [Release Channels and Upgrades](docs/release-channels.md) doc.
You can read more on the MicroK8s release channels in the [Release Channels and Upgrades](docs/release-channels.md) doc.
At any point you can check microk8s' availability with:
At any point you can check MicroK8s' availability with:
```
microk8s.status
......@@ -32,13 +32,13 @@ During installation you can use the `--wait-ready` flag to wait for the kubernet
microk8s.status --wait-ready
```
> In order to install microk8s make sure
> In order to install MicroK8s make sure
> - port 8080 is not used and
> - if you have AppArmor enabled (check with `sudo apparmor_status`) you do not have any other [dockerd installed](docs/dockerd.md). You can use the dockerd coming with microk8s.
> - if you have AppArmor enabled (check with `sudo apparmor_status`) you do not have any other [dockerd installed](docs/dockerd.md). You can use the dockerd coming with MicroK8s.
### Accessing Kubernetes
To avoid colliding with a `kubectl` already installed and to avoid overwriting any existing Kubernetes configuration file, microk8s adds a `microk8s.kubectl` command, configured to exclusively access the new microk8s install. When following instructions online, make sure to prefix `kubectl` with `microk8s.`.
To avoid colliding with a `kubectl` already installed and to avoid overwriting any existing Kubernetes configuration file, MicroK8s adds a `microk8s.kubectl` command, configured to exclusively access the new MicroK8s install. When following instructions online, make sure to prefix `kubectl` with `microk8s.`.
```
microk8s.kubectl get nodes
......@@ -56,18 +56,18 @@ This measure can be safely reverted at anytime by doing
```
snap unalias kubectl
```
If you already have `kubectl` installed and you want to use it to access the microk8s deployment you can export the cluster's config with:
If you already have `kubectl` installed and you want to use it to access the MicroK8s deployment you can export the cluster's config with:
```
microk8s.kubectl config view --raw > $HOME/.kube/config
```
Note: The API server on port 8080 is listening on all network interfaces. In its kubeconfig file microk8s is using the loopback interface, as you can see with `microk8s.kubectl config view`. The `microk8s.config` command will output a kubeconfig with the host machine's IP (instead of the 127.0.0.1) as the API server endpoint.
Note: The API server on port 8080 is listening on all network interfaces. In its kubeconfig file MicroK8s is using the loopback interface, as you can see with `microk8s.kubectl config view`. The `microk8s.config` command will output a kubeconfig with the host machine's IP (instead of the 127.0.0.1) as the API server endpoint.
### Kubernetes Addons
microk8s installs a barebones upstream Kubernetes. This means just the api-server, controller-manager, scheduler, kubelet, cni, kube-proxy are installed and run. Additional services like kube-dns and dashboard can be run using the `microk8s.enable` command
MicroK8s installs a barebones upstream Kubernetes. This means just the api-server, controller-manager, scheduler, kubelet, cni, kube-proxy are installed and run. Additional services like kube-dns and dashboard can be run using the `microk8s.enable` command
```
microk8s.enable dns dashboard
......@@ -86,37 +86,37 @@ With `microk8s.status` you can see the list of available addons and which ones a
- **dashboard**: Deploy kubernetes dashboard as well as grafana and influxdb. To access grafana point your browser to the url reported by `microk8s.kubectl cluster-info`.
- **storage**: Create a default storage class. This storage class makes use of the hostpath-provisioner pointing to a directory on the host. Persistent volumes are created under `${SNAP_COMMON}/default-storage`. Upon disabling this addon you will be asked if you want to delete the persistent volumes created.
- **ingress**: Create an ingress controller.
- **gpu**: Expose GPU(s) to microk8s by enabling the nvidia-docker runtime and nvidia-device-plugin-daemonset. Requires NVIDIA drivers to already be installed on the host system.
- **gpu**: Expose GPU(s) to MicroK8s by enabling the nvidia-docker runtime and nvidia-device-plugin-daemonset. Requires NVIDIA drivers to already be installed on the host system.
- **istio**: Deploy the core [Istio](https://istio.io/) services. You can use the `microk8s.istioctl` command to manage your deployments.
- **registry**: Deploy a docker private registry and expose it on `localhost:32000`. The storage addon will be enabled as part of this addon. To [use the registry](docs/registry.md) you can use the `microk8s.docker` command.
- **metrics-server**: Deploy the [Metrics Server](https://kubernetes.io/docs/tasks/debug-application-cluster/core-metrics-pipeline/#metrics-server).
### Stopping and Restarting microk8s
### Stopping and Restarting MicroK8s
You may wish to temporarily shutdown microk8s when not in use without un-installing it.
You may wish to temporarily shutdown MicroK8s when not in use without un-installing it.
microk8s can be shutdown with:
MicroK8s can be shutdown with:
```
microk8s.stop
```
microk8s can be restarted later with:
MicroK8s can be restarted later with:
```
microk8s.start
```
### Removing microk8s
### Removing MicroK8s
Before removing microk8s, use `microk8s.reset` to stop all running pods.
Before removing MicroK8s, use `microk8s.reset` to stop all running pods.
```
microk8s.reset
snap remove microk8s
```
### Configuring microk8s Services
### Configuring MicroK8s Services
The following systemd services will be running in your system:
- **snap.microk8s.daemon-apiserver**, is the [kube-apiserver](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-apiserver/) daemon started using the arguments in `${SNAP_DATA}/args/kube-apiserver`
- **snap.microk8s.daemon-controller-manager**, is the [kube-controller-manager](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) daemon started using the arguments in `${SNAP_DATA}/args/kube-controller-manager`
......@@ -136,7 +136,7 @@ sudo systemctl restart snap.microk8s.daemon-docker.service
### Deploy Behind a Proxy
To let microk8s use a proxy enter the proxy details in `${SNAP_DATA}/args/dockerd-env` and restart the docker daemon service with:
To let MicroK8s use a proxy enter the proxy details in `${SNAP_DATA}/args/dockerd-env` and restart the docker daemon service with:
```
sudo systemctl restart snap.microk8s.daemon-docker.service
```
......@@ -144,16 +144,16 @@ sudo systemctl restart snap.microk8s.daemon-docker.service
## Troubleshooting
To troubleshoot a non-functional microk8s deployment, start by running the `microk8s.inspect` command. This command performs a set of tests against microk8s and collects traces and logs in a report tarball. In case any of the aforementioned daemons are failing you will be urged to look at the respective logs with `journalctl -u snap.microk8s.<daemon>.service`. `microk8s.inspect` may also make suggestions on potential issues it may find. If you do not manage to resolve the issue you are facing please file a [bug](https://github.com/ubuntu/microk8s/issues) attaching the inspection report tarball.
To troubleshoot a non-functional MicroK8s deployment, start by running the `microk8s.inspect` command. This command performs a set of tests against MicroK8s and collects traces and logs in a report tarball. In case any of the aforementioned daemons are failing you will be urged to look at the respective logs with `journalctl -u snap.microk8s.<daemon>.service`. `microk8s.inspect` may also make suggestions on potential issues it may find. If you do not manage to resolve the issue you are facing please file a [bug](https://github.com/ubuntu/microk8s/issues) attaching the inspection report tarball.
Some common problems and solutions are listed below.
### My dns and dashboard pods are CrashLooping.
The [Kubenet](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) network plugin used by microk8s creates a `cbr0` interface when the first pod is created. If you have `ufw` enabled, you'll need to allow traffic on this interface:
The [Kubenet](https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) network plugin used by MicroK8s creates a `cbr0` interface when the first pod is created. If you have `ufw` enabled, you'll need to allow traffic on this interface:
`sudo ufw allow in on cbr0 && sudo ufw allow out on cbr0`
### My pods can't reach the internet (but my microk8s host machine can).
### My pods can't reach the internet (but my MicroK8s host machine can).
Make sure packets to/from the pod network interface can be forwarded
to/from the default interface on the host:
......@@ -163,8 +163,8 @@ or, if using `ufw`:
`sudo ufw default allow routed`
### My host machine changed IP and now microk8s is not working properly.
The host machine IP may change whenever you switch places with your laptop or you go through a suspend/resume cycle. The kubernetes API server advertises this IP (taken from the default interface) to all kubernetes cluster members. Services such as DNS and the dashboard will lose connectivity to API server in case the host IP changes. You will need to restart microk8s whenever this happens:
### My host machine changed IP and now MicroK8s is not working properly.
The host machine IP may change whenever you switch places with your laptop or you go through a suspend/resume cycle. The kubernetes API server advertises this IP (taken from the default interface) to all kubernetes cluster members. Services such as DNS and the dashboard will lose connectivity to API server in case the host IP changes. You will need to restart MicroK8s whenever this happens:
```
microk8s.stop
microk8s.start
......@@ -208,3 +208,7 @@ To speed-up a build you can reuse the binaries already downloaded from a previou
```
snap install microk8s_v1.10.3_amd64.snap --classic --dangerous
```
<p align="center">
<img src="https://assets.ubuntu.com/v1/9309d097-MicroK8s_SnapStore_icon.svg" width="150px">
</p>
\ No newline at end of file
# Dockerd in microk8s
# Dockerd in MicroK8s
The docker daemon used by microk8s is listening on `unix:///var/snap/microk8s/current/docker.sock`. You can access it with the `microk8s.docker` command. To skip the `microk8s` prefix we suggest you employ a snap alias:
The docker daemon used by MicroK8s is listening on `unix:///var/snap/microk8s/current/docker.sock`. You can access it with the `microk8s.docker` command. To skip the `microk8s` prefix we suggest you employ a snap alias:
```
sudo snap alias microk8s.docker docker
docker ps
......@@ -12,9 +12,9 @@ Export `DOCKER_HOST` for other tools using docker daemon:
export DOCKER_HOST="unix:///var/snap/microk8s/current/docker.sock"
```
When AppArmor is enabled all docker daemons running in a system will apply the same `docker-default` profile on running containers. Each daemon makes sure that it is the only process managing the docker containers (e.g., sending start stop signals). Effectively this allowes only one dockerd running on any host. Therefore, you have to make sure no other dockerd is running on your sytem along with microk8s.
When AppArmor is enabled all docker daemons running in a system will apply the same `docker-default` profile on running containers. Each daemon makes sure that it is the only process managing the docker containers (e.g., sending start stop signals). Effectively this allowes only one dockerd running on any host. Therefore, you have to make sure no other dockerd is running on your sytem along with MicroK8s.
Restarting microk8s' dockerd (`sudo systemctl restart snap.microk8s.daemon-docker`) or calling the `microk8s.reset` command will ensure the correct AppArmor profile is loaded.
Restarting MicroK8s' dockerd (`sudo systemctl restart snap.microk8s.daemon-docker`) or calling the `microk8s.reset` command will ensure the correct AppArmor profile is loaded.
## References
- Issue describing the AppArmor profile limitation: https://forum.snapcraft.io/t/commands-and-aliases/3950
# Private Registry Addon
Having a private docker registry can significantly improve your productivity by reducing the time spent in uploading and downloading docker images. The registry shipped with microk8s is hosted within the kubernetes cluster and is exposed as a NodePort service on port `32000` of the `localhost`. Note that this is an insecure registry and you may need to take extra steps to limit access to it.
Having a private docker registry can significantly improve your productivity by reducing the time spent in uploading and downloading docker images. The registry shipped with MicroK8s is hosted within the kubernetes cluster and is exposed as a NodePort service on port `32000` of the `localhost`. Note that this is an insecure registry and you may need to take extra steps to limit access to it.
## Installation and Usage
......@@ -12,7 +12,7 @@ microk8s.enable registry
As you can see in the applied [manifest](../microk8s-resources/actions/registry.yaml) a `20Gi` persistent volume is claimed for storing images. To satisfy this claim the storage addon is also enabled along with the registry.
The docker daemon used by microk8s is [configured to trust](../microk8s-resources/default-args/docker-daemon.json) this insecure registry. It is on this daemon we will have to talk to when we want to upload images. The easiest way to do so is by using the `microk8s.docker` client:
The docker daemon used by MicroK8s is [configured to trust](../microk8s-resources/default-args/docker-daemon.json) this insecure registry. It is on this daemon we will have to talk to when we want to upload images. The easiest way to do so is by using the `microk8s.docker` client:
```
microk8s.docker pull busybox
......
......@@ -5,13 +5,13 @@ Microk8s is a snap deploying Kubernetes. Upstream Kubernetes ships a new release
## Choosing the Right Channel
When installing microk8s you can select your desired upstream Kubernetes series with the corresponding snap channel. For example, to install microk8s and let it follow the `v1.12` release series you:
When installing MicroK8s you can select your desired upstream Kubernetes series with the corresponding snap channel. For example, to install MicroK8s and let it follow the `v1.12` release series you:
```
snap install microk8s --classic --channel=1.12/stable
```
If you omit the `--channel` argument microk8s will follow the latest stable upstream Kubernetes. This means that your deployment will eventually upgrade to a new release series. At the time of this writing you will get `v1.12.0` with:
If you omit the `--channel` argument MicroK8s will follow the latest stable upstream Kubernetes. This means that your deployment will eventually upgrade to a new release series. At the time of this writing you will get `v1.12.0` with:
```
snap install microk8s --classic
......@@ -20,7 +20,7 @@ snap install microk8s --classic
Since no `--channel` is specified such deployment will eventually upgrade to `v1.13.0`.
Switching from one channel to another is done with [`snap refresh --channel=<new_channel>`](https://docs.snapcraft.io/reference/snap-command#refresh). For example, switch microk8s to the v1.11 release series with:
Switching from one channel to another is done with [`snap refresh --channel=<new_channel>`](https://docs.snapcraft.io/reference/snap-command#refresh). For example, switch MicroK8s to the v1.11 release series with:
```
snap install microk8s --channel=1.11/stable
......@@ -28,15 +28,15 @@ snap install microk8s --channel=1.11/stable
## Availability of Releases and Channels
The `*/stable` channels serve the latest stable upstream Kubernetes release of the respective release series. Upstream releases are propagated to the microk8s snap in about a week. This means your microk8s will upgrade to the latest upstream release in your selected channel roughly one week after the upstream release.
The `*/stable` channels serve the latest stable upstream Kubernetes release of the respective release series. Upstream releases are propagated to the MicroK8s snap in about a week. This means your MicroK8s will upgrade to the latest upstream release in your selected channel roughly one week after the upstream release.
The `*/candidate` and `*/beta` channels get updated within hours of an upstream release. Getting a microk8s deployment pointing to `1.12/beta` is as simple as:
The `*/candidate` and `*/beta` channels get updated within hours of an upstream release. Getting a MicroK8s deployment pointing to `1.12/beta` is as simple as:
```
snap install microk8s --classic --channel=1.12/beta
```
The `*/edge` channels get updated for each microk8s patch or upstream Kubernetes release.
The `*/edge` channels get updated for each MicroK8s patch or upstream Kubernetes release.
Keep in mind that edge and beta are snap constructs and do not relate to Kubernetes release names.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment