docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improvements to SLES install and BTRFS (#2618)

This commit is contained in:
Misty Stanley-Jones 2017-04-04 14:09:29 -07:00 committed by GitHub
parent d59ed36cc1
commit 27bc66e009
4 changed files with 166 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
cs-engine/1.12/index.md
View File

@ -126,6 +126,7 @@ to update its RHEL kernel.
9. Log out and log back in to have your new permissions take effect. 9. Log out and log back in to have your new permissions take effect.
### Install on Ubuntu 14.04 LTS or 16.04 LTS ### Install on Ubuntu 14.04 LTS or 16.04 LTS
1. Install packages to allow `apt` to use a repository over HTTPS: 1. Install packages to allow `apt` to use a repository over HTTPS:
@ -295,6 +296,9 @@ to update its RHEL kernel.
Log out and log back in to have your new permissions take effect. Log out and log back in to have your new permissions take effect.
7. [Configure Btrfs for graph storage](/engine/userguide/storagedriver/btrfs-driver.md).
This is the only graph storage driver supported on SLES.
## Install using packages ## Install using packages
If you need to install Docker on an air-gapped system with no access to the If you need to install Docker on an air-gapped system with no access to the

3
cs-engine/1.13/index.md
View File

@ -298,6 +298,9 @@ to update its RHEL kernel.
Log out and log back in to have your new permissions take effect. Log out and log back in to have your new permissions take effect.
7. [Configure Btrfs for graph storage](/engine/userguide/storagedriver/btrfs-driver.md).
This is the only graph storage driver supported on SLES.
## Install using packages ## Install using packages
If you need to install Docker on an air-gapped system with no access to the If you need to install Docker on an air-gapped system with no access to the

26
engine/installation/linux/suse.md
View File

@ -78,14 +78,20 @@ the repository.
#### Set up the repository #### Set up the repository
Use the following command to set up the **stable** repository, using the 1. Use the following command to set up the **stable** repository, using the
Docker EE repository URL you located in the [prerequisites](#prerequisites). Docker EE repository URL you located in the [prerequisites](#prerequisites).
```bash ```bash
$ sudo zypper addrepo \ $ sudo zypper addrepo \
<DOCKER-EE-URL>/12.3/x86_64/stable-{{ minor-version }} \ <DOCKER-EE-URL>/12.3/x86_64/stable-{{ minor-version }} \
docker-ee-stable docker-ee-stable
``` ```
2. Import the GPG key from the repository.
```bash
$ sudo rpm --import <DOCKER-EE-URL/gpg
```
#### Install Docker EE #### Install Docker EE
@ -158,9 +164,9 @@ $ sudo zypper addrepo \
container runs, it prints an informational message and exits. container runs, it prints an informational message and exits.
Docker EE is installed and running. You need to use `sudo` to run Docker Docker EE is installed and running. You need to use `sudo` to run Docker
commands. Continue to [Linux postinstall](linux-postinstall.md) to allow commands. Continue to [Linux postinstall](linux-postinstall.md) to configure the
non-privileged users to run Docker commands and for other optional configuration graph storage driver, allow non-privileged users to run Docker commands, and for
steps. other optional configuration steps.
#### Upgrade Docker EE #### Upgrade Docker EE

215
engine/userguide/storagedriver/btrfs-driver.md
View File

@ -17,7 +17,8 @@ copy-on-write, and snapshotting.
This article refers to Docker's Btrfs storage driver as `btrfs` and the overall This article refers to Docker's Btrfs storage driver as `btrfs` and the overall
Btrfs Filesystem as Btrfs. Btrfs Filesystem as Btrfs.
> **Note**: The [Commercially Supported Docker Engine (CS-Engine)](https://www.docker.com/compatibility-maintenance) does not currently support the `btrfs` storage driver. > **Note**: Btrfs is not supported on every Linux version and Docker edition.
> It is only supported on Docker CE on Ubuntu, and Docker EE / CS Engine on SLES.
## The future of Btrfs ## The future of Btrfs
@ -140,7 +141,7 @@ filesystems like Btrfs and incurs very little overhead.
With Btrfs, writing and updating lots of small files can result in slow With Btrfs, writing and updating lots of small files can result in slow
performance. More on this later. performance. More on this later.
## Configuring Docker with Btrfs ## Configure Docker with Btrfs
The `btrfs` storage driver only operates on a Docker host where The `btrfs` storage driver only operates on a Docker host where
`/var/lib/docker` is mounted as a Btrfs filesystem. The following procedure `/var/lib/docker` is mounted as a Btrfs filesystem. The following procedure
@ -163,103 +164,173 @@ loaded. To verify this, use the following command:
btrfs btrfs
### Configure Btrfs on Ubuntu 14.04 LTS ### Configure Btrfs on Ubuntu
Assuming your system meets the prerequisites, do the following: > **Note**: Btrfs is not supported on Docker EE or Docker CS Engine for Ubuntu.
1. Install the "btrfs-tools" package. 1. Install the `btrfs-tools` package.
$ sudo apt-get install btrfs-tools ```bash
$ sudo apt-get install btrfs-tools
```
Reading package lists... Done 2. Format the Btrfs filesystem across a pool of one or more devices by passing
Building dependency tree the devices to the `mkfs.btrfs` command. Replace `<DEVICE>` with the
<output truncated> actual device names.
2. Create the Btrfs storage pool. ```bash
$ sudo mkfs.btrfs -f /dev/<DEVICE> /dev/<DEVICE> /dev/<DEVICE>
```
Btrfs storage pools are created with the `mkfs.btrfs` command. Passing There are many more options for Btrfs, including striping and RAID. See the
multiple devices to the `mkfs.btrfs` command creates a pool across all of those [Btrfs documentation](https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices).
devices. Here you create a pool with a single device at `/dev/xvdb`.
$ sudo mkfs.btrfs -f /dev/xvdb 3. Stop Docker and back up the contents of `/var/lib/docker/`.
WARNING! - Btrfs v3.12 IS EXPERIMENTAL ```bash
WARNING! - see http://btrfs.wiki.kernel.org before using $ sudo service docker stop
$ sudo cp -au /var/lib/docker /var/lib/docker.bk
$ sudo rm -rf /var/lib/docker/*
```
Turning ON incompat feature 'extref': increased hardlink limit per file to 65536 4. Configure the Btrfs volume to automatically mount to `/var/lib/docker`.
fs created label (null) on /dev/xvdb As root (`sudo` may not be sufficient), edit `/etc/fstab` and add the
nodesize 16384 leafsize 16384 sectorsize 4096 size 4.00GiB following line at the end, Replace `/dev/<DEVICE>` with any one of the devices
Btrfs v3.12 you used in step 2. You can choose to specify the device's UUID instead of the
device path. Refer to `man 5 fstab` for more information.
Be sure to substitute `/dev/xvdb` with the appropriate device(s) on your ```none
system. /dev/<DEVICE> /var/lib/docker btrfs defaults 0 1
```
> **Warning**: Take note of the warning about Btrfs being experimental. As 5. Mount the Btrfs volume:
noted earlier, Btrfs is not currently recommended for production deployments
unless you already have extensive experience.
3. If it does not already exist, create a directory for the Docker host's local ```bash
storage area at `/var/lib/docker`. $ sudo mount /var/lib/docker
```
$ sudo mkdir /var/lib/docker Copy the old Docker contents to `/var/lib/docker`.
4. Configure the system to automatically mount the Btrfs filesystem each time the system boots. ```bash
$ sudo cp -r /var/lib/docker.bk/* /var/lib/docker
```
a. Obtain the Btrfs filesystem's UUID. 6. Configure Docker so that it realizes it is using Btrfs for graph storage.
Edit or create the file `/etc/docker/daemon.json`. If it is a new file, add
the following contents. If it is an existing file, add the key and value
only, being careful to end the line with a comma if it is not the final
line before an ending curly bracket (`}`).
$ sudo blkid /dev/xvdb ```json
{
"storage-driver": "btrfs"
}
```
/dev/xvdb: UUID="a0ed851e-158b-4120-8416-c9b072c8cf47" UUID_SUB="c3927a64-4454-4eef-95c2-a7d44ac0cf27" TYPE="btrfs" 7. Start Docker.
b. Create an `/etc/fstab` entry to automatically mount `/var/lib/docker` ```bash
each time the system boots. Either of the following lines will work, just $ sudo service docker start
remember to substitute the UUID value with the value obtained from the previous ```
command.
/dev/xvdb /var/lib/docker btrfs defaults 0 0 Verify that Btrfs is being used with the following command:
UUID="a0ed851e-158b-4120-8416-c9b072c8cf47" /var/lib/docker btrfs defaults 0 0
5. Mount the new filesystem and verify the operation. ```bash
$ docker info |grep Storage
$ sudo mount -a Storage Driver: btrfs
```
$ mount 8. After you have verified that Docker is working as expected, remove the
backup copy of the Docker files.
/dev/xvda1 on / type ext4 (rw,discard) ```bash
<output truncated> $ sudo rm -rf /var/lib/docker.bk
/dev/xvdb on /var/lib/docker type btrfs (rw) ```
The last line in the output above shows the `/dev/xvdb` mounted at ### Configure Btrfs on SLES
`/var/lib/docker` as Btrfs.
Now that you have a Btrfs filesystem mounted at `/var/lib/docker`, the daemon 1. Install the Btrfs utilities.
should automatically load with the `btrfs` storage driver.
1. Start the Docker daemon. ```bash
$ sudo zypper install btrfsprogs
```
$ sudo service docker start 2. Format the Btrfs filesystem across a pool of one or more devices by passing
the devices to the `mkfs.btrfs` command. Replace `<DEVICE>` with the
actual device names.
docker start/running, process 2315 ```bash
$ sudo mkfs.btrfs -f /dev/<DEVICE> /dev/<DEVICE> /dev/<DEVICE>
```
The procedure for starting the Docker daemon may differ depending on the There are many more options for Btrfs, including striping and RAID. See the
Linux distribution you are using. [Btrfs documentation](https://btrfs.wiki.kernel.org/index.php/Using_Btrfs_with_Multiple_Devices).
You can force the Docker daemon to start with the `btrfs` storage 3. Stop Docker and back up the contents of `/var/lib/docker/`.
driver by either passing the `--storage-driver=btrfs` flag to the `docker
daemon` at startup, or adding it to the `DOCKER_OPTS` line to the Docker config
file.
2. Verify the storage driver with the `docker info` command. ```bash
$ sudo service docker stop
$ sudo cp -au /var/lib/docker /var/lib/docker.bk
$ sudo rm -rf /var/lib/docker/*
```
$ sudo docker info 4. Configure the Btrfs volume to automatically mount to `/var/lib/docker`.
As root (`sudo` may not be sufficient), edit `/etc/fstab` and add the
following line at the end, Replace `/dev/<DEVICE>` with any one of the devices
you used in step 2. You can choose to specify the device's UUID instead of the
device path. Refer to `man 5 fstab` for more information.
Containers: 0 ```none
Images: 0 /dev/<DEVICE> /var/lib/docker btrfs defaults 0 1
Storage Driver: btrfs ```
[...]
Your Docker host is now configured to use the `btrfs` storage driver. Save the file.
5. Mount the Btrfs volume:
```bash
$ sudo mount /var/lib/docker
```
Copy the old Docker contents to `/var/lib/docker`.
```bash
$ sudo cp -r /var/lib/docker.bk/* /var/lib/docker
```
6. Configure Docker so that it realizes it is using Btrfs for graph storage.
Edit or create the file `/etc/docker/daemon.json`. If it is a new file, add
the following contents. If it is an existing file, add the key and value
only, being careful to end the line with a comma if it is not the final
line before an ending curly bracket (`}`).
```json
{
"storage-driver": "btrfs"
}
```
7. Start Docker.
```bash
$ sudo service docker start
```
Verify that Btrfs is being used with the following command:
```bash
$ docker info |grep Storage
Storage Driver: btrfs
```
8. After you have verified that Docker is working as expected, remove the
backup copy of the Docker files.
```bash
$ sudo rm -rf /var/lib/docker.bk
```
## Btrfs and Docker performance ## Btrfs and Docker performance
@ -312,14 +383,14 @@ any of the potential overheads introduced by thin provisioning and
copy-on-write. For this reason, you should place heavy write workloads on data copy-on-write. For this reason, you should place heavy write workloads on data
volumes. volumes.
- **Balance BTRFS**. Enable a cronjob to rebalance your BTRFS devices. e.g. - **Balance BTRFS**. Enable a cronjob to rebalance your BTRFS devices. e.g.
Spread the subvolume's blocks evenly across your raid devices, and reclaim Spread the subvolume's blocks evenly across your raid devices, and reclaim
unused blocks. Without doing this, snapshots and subvolumes that docker unused blocks. Without doing this, snapshots and subvolumes that docker
removes will leave allocated blocks fillingup the BTRFS root volume. Once full removes will leave allocated blocks fillingup the BTRFS root volume. Once full
you won't be able to re-balance, resulting in a potentially unrecoverable you won't be able to re-balance, resulting in a potentially unrecoverable
state without adding an additional storage device. If you would rather not state without adding an additional storage device. If you would rather not
automate this with crond, another option is to run a re-balance manually automate this with crond, another option is to run a re-balance manually
outside peak use times since the operation can be disk I/O intensive. This outside peak use times since the operation can be disk I/O intensive. This
command will claim all chunks that are 1% used or less: command will claim all chunks that are 1% used or less:
$ sudo btrfs filesystem balance start -dusage=1 /var/lib/docker $ sudo btrfs filesystem balance start -dusage=1 /var/lib/docker