doc: Remove base image documents
The feature was removed in v0.6.0. Signed-off-by: Sheng Yang <sheng.yang@rancher.com>
This commit is contained in:
parent
6645767866
commit
2cc6d2608c
@ -207,7 +207,6 @@ More examples are available at `./examples/`
|
||||
### [Settings](./docs/settings.md)
|
||||
### [Multiple disks](./docs/multidisk.md)
|
||||
### [iSCSI](./docs/iscsi.md)
|
||||
### [Base image](./docs/base-image.md)
|
||||
### [Kubernetes workload in Longhorn UI](./docs/k8s-workload.md)
|
||||
### [Storage Tags](./docs/storage-tags.md)
|
||||
### [Customized default setting](./docs/customized-default-setting.md)
|
||||
|
@ -1,250 +0,0 @@
|
||||
# Base Image Support
|
||||
|
||||
Longhorn supports creation of block devices backed by a base image. Longhorn
|
||||
base images are packaged as Docker images. Public or private registries may
|
||||
be used as a distribution mechanism for your Docker base images.
|
||||
|
||||
## Usage
|
||||
|
||||
Volumes backed by a base image can be created in three ways.
|
||||
|
||||
1. [UI](#ui) - Create Longhorn volumes exposed as block device or iSCSI target
|
||||
2. [Flexvolume Driver](#flexvolume-driver) - Create Longhorn block devices and consume in Kubernetes pods
|
||||
3. [CSI Driver](#csi-driver) - (Newer) Create Longhorn block devices and consume in Kubernetes pods
|
||||
|
||||
### UI
|
||||
|
||||
On the `Volume` tab, click the `Create Volume` button. The `Base Image` field
|
||||
expects a Docker image name such as `rancher/vm-ubuntu:16.04.4-server-amd64`.
|
||||
|
||||
### Flexvolume Driver
|
||||
|
||||
The flexvolume driver supports volumes backed by base image. Below is a sample
|
||||
Flexvolume definition including `baseImage` option.
|
||||
|
||||
```
|
||||
name: flexvol
|
||||
flexVolume:
|
||||
driver: "rancher.io/longhorn"
|
||||
fsType: "ext4"
|
||||
options:
|
||||
size: "32Mi"
|
||||
numberOfReplicas: "3"
|
||||
staleReplicaTimeout: "20"
|
||||
fromBackup: ""
|
||||
baseImage: "rancher/longhorn-test:baseimage-ext4"
|
||||
```
|
||||
|
||||
You do not need to (and probably shouldn't) explicitly set filesystem type
|
||||
`fsType` when base image is present. If you do, it must match the base image's
|
||||
filesystem or the flexvolume driver will return an error.
|
||||
|
||||
Try it out for yourself. Make sure the Longhorn driver deployer specifies flag
|
||||
`--driver flexvolume`, otherwise a different driver may be deployed. The
|
||||
following example creates an nginx pod serving content from a flexvolume with
|
||||
a base image and is accessible from a service.
|
||||
|
||||
```
|
||||
kubectl create -f https://raw.githubusercontent.com/rancher/longhorn-manager/master/examples/flexvolume/example_baseimage.yaml
|
||||
```
|
||||
|
||||
Wait until the pod is running.
|
||||
|
||||
```
|
||||
kubectl get po/flexvol-baseimage -w
|
||||
```
|
||||
|
||||
Query for the service you created.
|
||||
|
||||
```
|
||||
kubectl get svc/flexvol-baseimage
|
||||
```
|
||||
|
||||
Your service should look similar.
|
||||
|
||||
```
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
service/flexvol-baseimage LoadBalancer 10.43.153.186 <pending> 80:31028/TCP 2m
|
||||
```
|
||||
|
||||
Now let's access something packaged inside the base image through the Nginx
|
||||
webserver, exposed by the `LoadBalancer` service. If you have LoadBalancer
|
||||
support and `EXTERNAL-IP` is set, navigate to the following URL.
|
||||
|
||||
```
|
||||
http://<EXTERNAL-IP>/guests/hd/party-wizard.gif
|
||||
```
|
||||
|
||||
Otherwise, navigate to the following URL where `NODE-IP` is the external IP
|
||||
address of any Kubernetes node and `NODE-PORT` is the second port in the
|
||||
service (`31028` in the example service above).
|
||||
|
||||
```
|
||||
http://<NODE-IP>:<NODE-PORT>/guests/hd/party-wizard.gif
|
||||
```
|
||||
|
||||
Finally, tear down the pod and service.
|
||||
|
||||
```
|
||||
kubectl delete -f https://raw.githubusercontent.com/rancher/longhorn-manager/master/examples/flexvolume/example_baseimage.yaml
|
||||
```
|
||||
|
||||
### CSI Driver
|
||||
|
||||
The CSI driver supports volumes backed by base image. Below is a sample
|
||||
StorageClass definition including `baseImage` option.
|
||||
|
||||
```
|
||||
kind: StorageClass
|
||||
apiVersion: storage.k8s.io/v1
|
||||
metadata:
|
||||
name: example
|
||||
provisioner: rancher.io/longhorn
|
||||
parameters:
|
||||
numberOfReplicas: '3'
|
||||
staleReplicaTimeout: '30'
|
||||
fromBackup: ''
|
||||
baseImage: rancher/longhorn-test:baseimage-ext4
|
||||
```
|
||||
|
||||
Let's walk through an example. First, ensure the CSI Plugin is deployed.
|
||||
|
||||
```
|
||||
kubectl -n longhorn-system get daemonset.apps/longhorn-csi-plugin
|
||||
```
|
||||
|
||||
The following example creates an nginx statefulset with two replicas serving
|
||||
content from two csi-provisioned volumes backed by a base image. The
|
||||
statefulset is accessible from a service.
|
||||
|
||||
```
|
||||
kubectl create -f https://raw.githubusercontent.com/rancher/longhorn-manager/master/examples/provisioner_with_baseimage.yaml
|
||||
```
|
||||
|
||||
Wait until both pods are running.
|
||||
|
||||
```
|
||||
kubectl -l app=provisioner-baseimage get po -w
|
||||
```
|
||||
|
||||
Query for the service you created.
|
||||
|
||||
```
|
||||
kubectl get svc/csi-baseimage
|
||||
```
|
||||
|
||||
Your service should look similar.
|
||||
|
||||
```
|
||||
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
|
||||
csi-baseimage LoadBalancer 10.43.47.129 <pending> 80:32768/TCP 4m
|
||||
```
|
||||
|
||||
Now let's access something packaged inside the base image through the Nginx
|
||||
webserver, exposed by the `LoadBalancer` service. If you have LoadBalancer
|
||||
support and `EXTERNAL-IP` is set, navigate to the following URL.
|
||||
|
||||
```
|
||||
http://<EXTERNAL-IP>/guests/hd/party-wizard.gif
|
||||
```
|
||||
|
||||
Otherwise, navigate to the following URL where `NODE-IP` is the external IP
|
||||
address of any Kubernetes node and `NODE-PORT` is the second port in the
|
||||
service (`32768` in the example service above).
|
||||
|
||||
```
|
||||
http://<NODE-IP>:<NODE-PORT>/guests/hd/party-wizard.gif
|
||||
```
|
||||
|
||||
Finally, tear down the pod and service.
|
||||
|
||||
```
|
||||
kubectl delete -f https://raw.githubusercontent.com/rancher/longhorn-manager/master/examples/provisioner_with_baseimage.yaml
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
Creating and packaging an empty base image is a very simple process.
|
||||
|
||||
1. [Install QEMU](https://en.wikibooks.org/wiki/QEMU/Installing_QEMU).
|
||||
2. Create a qcow2 image.
|
||||
|
||||
```
|
||||
qemu-img create -f qcow2 example.qcow2 4G
|
||||
```
|
||||
|
||||
3. Create the `Dockerfile` file with the following contents:
|
||||
|
||||
```
|
||||
FROM busybox
|
||||
COPY example.qcow2 /base_image/example.qcow2
|
||||
```
|
||||
|
||||
4. Build and publish the image:
|
||||
|
||||
```
|
||||
DOCKERHUB_ACCT=rancher
|
||||
docker build -t ${DOCKERHUB_ACCT}/longhorn-example:baseimage .
|
||||
docker push ${DOCKERHUB_ACCT}/longhorn-example:baseimage
|
||||
```
|
||||
|
||||
That's it! Your (empty) base image is ready for (no) use. Let's now explore
|
||||
some use cases for a base image and what we should do to our `example.qcow2`
|
||||
before building and publishing.
|
||||
|
||||
### Simple Filesystem
|
||||
|
||||
Suppose we want to store some static web assets in a volume. We have our qcow2
|
||||
image and the web assets, but how to put the assets in the image?
|
||||
|
||||
On a Linux machine, load the network block device module.
|
||||
|
||||
```
|
||||
sudo modprobe nbd
|
||||
```
|
||||
|
||||
Use `qemu-nbd` to expose the image as a network block device.
|
||||
|
||||
```
|
||||
sudo qemu-nbd -f qcow2 -c /dev/nbd0 example.qcow2
|
||||
```
|
||||
|
||||
The raw block device needs a filesystem. Consider your infrastructure and
|
||||
choose an appropriate filesystem. We will use EXT4 filesystem.
|
||||
|
||||
```
|
||||
sudo mkfs -t ext4 /dev/nbd0
|
||||
```
|
||||
|
||||
Mount the filesystem.
|
||||
|
||||
```
|
||||
mkdir -p example
|
||||
sudo mount /dev/nbd0 example
|
||||
```
|
||||
|
||||
Copy web assets to filesystem.
|
||||
|
||||
```
|
||||
cp /web/assets/* example/
|
||||
```
|
||||
|
||||
Unmount the filesystem, shutdown `qemu-nbd`, cleanup.
|
||||
|
||||
```
|
||||
sudo umount example
|
||||
sudo killall qemu-nbd
|
||||
rmdir example
|
||||
```
|
||||
|
||||
Optionally, compress the image.
|
||||
|
||||
```
|
||||
qemu-img convert -c -O qcow2 example.qcow2 example.compressed.qcow2
|
||||
```
|
||||
|
||||
Follow the build and publish image steps and you are done. [Example script](https://raw.githubusercontent.com/rancher/longhorn-tests/master/manager/test_containers/baseimage/generate.sh).
|
||||
|
||||
### Virtual Machine
|
||||
|
||||
See [this document](https://github.com/rancher/vm/blob/master/docs/images.md) for the basic procedure of preparing Virtual Machine images.
|
Loading…
Reference in New Issue
Block a user