rancher/os
1
0
Fork 1
mirror of https://github.com/rancher/os.git synced 2025-09-15 22:49:08 +00:00
Code Issues Releases Wiki Activity

import the rancherOS docs so we can write docs for the next release

Browse Source 
Signed-off-by: Sven Dowideit <SvenDowideit@home.org.au>
This commit is contained in:
Sven Dowideit
2016-11-02 11:57:09 +10:00
parent 35ce5cd8b5
commit 980ee23130
197 changed files with 45993 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
docs/os/system-services/adding-system-services/index.md Normal file
View File

@@ -0,0 +1,133 @@
---
title: Adding System Services in RancherOS
layout: os-default
redirect_from:
- os/system-services/
- os/configuration/system-services/
---
## System Services
A system service is a container that can be run in either System Docker or Docker. Rancher provides services that are already available in RancherOS by adding them to the [os-services repo](https://github.com/rancher/os-services). Anything in the `index.yml` file from the repository for the tagged release will be an available system service when using the `ros service list` command.
### Enabling and Starting System Services
For any services that are listed from the `ros service list`, they can be enabled by running a single command. After enabling a service, you will need to run start the service.
```
# List out available system services
$ sudo ros service list
disabled amazon-ecs-agent
disabled kernel-headers
disabled kernel-headers-system-docker
disabled open-vm-tools
# Enable a system service
$ sudo ros service enable kernel-headers
# Start a system service
$ sudo ros service up -d kernel-headers
```
### Disabling and Removing System Services
In order to stop a system service from running, you will need to stop and disable the system service.
```
# List out available system services
$ sudo ros service list
disabled amazon-ecs-agent
enabled kernel-headers
disabled kernel-headers-system-docker
disabled open-vm-tools
# Disable a system service
$ sudo ros service disable kernel-headers
# Stop a system service
$ sudo ros service stop kernel-headers
# Remove the containers associated with the system service
$ sudo ros service down kernel-headers
```
<br>
If you want to remove a system service from the list of service, just delete the service.
```
$ sudo ros service delete <serviceName>
```
### Custom System Services
You can also create your own system service in [Docker Compose](https://docs.docker.com/compose/) format. After creating your own custom service, you can launch it in RancherOS in a couple of methods. The service could be directly added to the [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config), or a `docker-compose.yml` file could be saved at a http(s) url location or in a specific directory of RancherOS.
#### Launching Services through Cloud-Config
If you want to boot RancherOS with a system service running, you can add the service to the cloud-config that is passed to RancherOS. When RancherOS starts, this service will automatically be started.
```yaml
#cloud-config
rancher:
services:
nginxapp:
image: nginx
restart: always
```
#### Launching Custom System Services inside RancherOS
If you already have RancherOS running, you can start a system service by saving a `docker-compose.yml` file at `/var/lib/rancher/conf/`.
```yaml
nginxapp:
image: nginx
restart: always
```
To enable a custom system service from the file location, the command must indicate the file location if saved in RancherOS. If the file is saved at a http(s) url, just use the http(s) url when enabling/disabling.
```
# Enable the system service saved in /var/lib/rancher/conf
$ sudo ros service enable /var/lib/rancher/conf/example.yml
# Enable a system service saved at a http(s) url
$ sudo ros service enable https://mydomain.com/example.yml
```
<br>
After the custom system service is enabled, you can start the service using `sudo ros service up -d <serviceName>`. The `<serviceName>` will be the names of the services inside the `docker-compose.yml`.
```
$ sudo ros service up -d nginxapp
# If you have more than 1 service in your docker-compose.yml, add all service names to the command
$ sudo ros service up -d service1 service2 service3
```
### System Docker vs. Docker
RancherOS uses labels to determine if the container should be deployed in System Docker. By default without the label, the container will be deployed in Docker.
```yaml
labels:
- io.rancher.os.scope=system
```
### Labels
We use labels to determine how to handle the service containers.
Key | Value |Description
----|-----|---
`io.rancher.os.detach` | Default: `true` | Equivalent of `docker run -d`. If set to `false`, equivalent of `docker run --detach=false`
`io.rancher.os.scope` | `system` | Use this label to have the container deployed in System Docker instead of Docker.
`io.rancher.os.before`/`io.rancher.os.after` | Service Names (Comma separated list is accepted) | Used to determine order of when containers should be started.
`io.rancher.os.createonly` | Default: `false` | When set to `true`, only a `docker create` will be performed and not a `docker start`.
`io.rancher.os.reloadconfig` | Default: `false`| When set to `true`, it reloads the configuration.
#### Example of how to order container deployment
```yaml
foo:
labels:
# Start foo before bar is launched
io.rancher.os.before: bar
# Start foo after baz has been launched
io.rancher.os.after: baz
```

109
docs/os/system-services/built-in-system-services/index.md Normal file
View File

@@ -0,0 +1,109 @@
---
title: Built-in System Services in RancherOS
layout: os-default
---
## Built-in System Services
To launch RancherOS, we have built-in system services. They are defined in the [Docker Compose](https://docs.docker.com/compose/compose-file/) format, and can be found in the default system config file, `/usr/share/ros/os-config.yml`. You can [add your own system services]({{site.baseurl}}/os/system-services/) or override services in the cloud-config.
In start up order, here are the groups of services:
1. Device and power management:
- udev-cold
- udev
- acpid
2. syslog
3. System configuration and networking:
- preload-system-images
- cloud-init-pre
- network-pre
- ntp
- cloud-init
- network
4. User interaction:
- console
- docker
5. Post configuration:
- preload-user-images
### preload-system-images & preload-user-images
Read more about [pre-packing Docker images]({{site.baseurl}}/os/configuration/prepacking-docker-images/).
### cloud-init-pre
User-data (i.e. [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config)) and metadata from cloud provider, VM runtime, or a management service, is loaded in this service.
The user-data is written to:
* `/var/lib/rancher/conf/cloud-config.d/boot.yml` - If the user-data is a cloud-config, i.e. begins with `#cloud-config` and is YAML format.
* `/var/lib/rancher/conf/cloud-config-script` - If the user-data is a script, i.e begins with `#!`.
* `/var/lib/rancher/conf/metadata` - If it is serialized cloud provider metadata.
It is configured by the `rancher.cloud_init.datasources` list in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config). It is pre-configured in cloud-provider specific images (e.g. AWS, GCE).
### network-pre
During this service, networking is set up, e.g. hostname, interfaces, and DNS.
It is configured by `hostname` and `rancher.network`[settings]({{site.baseurl}}/os/networking/) in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
### ntp
Runs `ntpd` in a System Docker container.
### cloud-init
It does the same thing as cloud-init-pre, but in this step, it can also use the network to fetch user-data and metadata (e.g. in cloud providers).
### network
Completes setting up networking with configuration obtained by cloud-init.
### console
This service provides the RancherOS user interface by running `sshd` and `getty`. It completes the RancherOS configuration on start up:
1. If the `rancher.password=<password>` kernel parameter exists, it sets `<password>` as the password for the `rancher` user.
2. If there are no host SSH keys, it generates host SSH keys and saves them under `rancher.ssh.keys` in [cloud-config]({{site.baseurl}}/os/configuration/#cloud-config).
3. Runs `cloud-init -execute`, which does the following:
* Updates `.ssh/authorized_keys` in `/home/rancher` and `/home/docker` from [cloud-config]({{site.baseurl}}/os/configuration/ssh-keys/) and metadata.
* Writes files specified by the `write_files` [cloud-config]({{site.baseurl}}/os/configuration/write-files/) setting.
* Resizes the device specified by the `rancher.resize_device` [cloud-config]({{site.baseurl}}/os/configuration/resizing-device-partition/) setting.
* Mount devices specified in the `mounts` [cloud-config]({{site.baseurl}}/os/configuration/additional-mounts/) setting.
* Set sysctl parameters specified in the`rancher.sysctl` [cloud-config]({{site.baseurl}}/os/configuration/sysctl/) setting.
4. If user-data contained a file that started with `#!`, then a file would be saved at `/var/lib/rancher/conf/cloud-config-script` during cloud-init and then executed. Any errors are ignored.
5. Runs `/opt/rancher/bin/start.sh` if it exists and is executable. Any errors are ignored.
6. Runs `/etc/rc.local` if it exists and is executable. Any errors are ignored.
### docker
This system service runs the user docker daemon. Normally it runs inside the console system container by running `docker-init` script which, in turn, looks for docker binaries in `/opt/bin`, `/usr/local/bin` and `/usr/bin`, adds the first found directory with docker binaries to PATH and runs `dockerlaunch docker daemon` appending the passed arguments.
Docker daemon args are read from `rancher.docker.args` cloud-config property (followed by `rancher.docker.extra_args`).
### RancherOS Configuration Load Order
[Cloud-config]({{site.baseurl}}/os/configuration/#cloud-config/) is read by system services when they need to get configuration. Each additional file overwrites and extends the previous configuration file.
1. `/usr/share/ros/os-config.yml` - This is the system default configuration, which should **not** be modified by users.
2. `/usr/share/ros/oem/oem-config.yml` - This will typically exist by OEM, which should **not** be modified by users.
3. Files in `/var/lib/rancher/conf/cloud-config.d/` ordered by filename. If a file is passed in through user-data, it is written by cloud-init and saved as `/var/lib/rancher/conf/cloud-config.d/boot.yml`.
4. `/var/lib/rancher/conf/cloud-config.yml` - If you set anything with `ros config set`, the changes are saved in this file.
5. Kernel parameters with names starting with `rancher`.
6. `/var/lib/rancher/conf/metadata` - Metadata added by cloud-init.

36
docs/os/system-services/environment/index.md Normal file
View File

@@ -0,0 +1,36 @@
---
title: Environment
layout: os-default
---
## Environment
---
The [environment key](https://docs.docker.com/compose/yml/#environment) can be used to customize system services. When a value is not assigned, RancherOS looks up the value from the `rancher.environment` key.
In the example below, `ETCD_DISCOVERY` will be set to `https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7` for the `etcd` service.
```yaml
rancher:
environment:
ETCD_DISCOVERY: https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7
services:
etcd:
...
environment:
- ETCD_DISCOVERY
```
Wildcard globbing is also supported. In the example below, `ETCD_DISCOVERY` will be set as in the previous example, along with any other environment variables beginning with `ETCD_`.
```yaml
rancher:
environment:
ETCD_DISCOVERY: https://discovery.etcd.io/d1cd18f5ee1c1e2223aed6a1734719f7
services:
etcd:
...
environment:
- ETCD_*
```

79
docs/os/system-services/system-docker-volumes/index.md Normal file
View File

@@ -0,0 +1,79 @@
---
title: System Docker Volumes
layout: os-default
---
## System Docker Volumes
---
A few services are containers in `created` state. Their purpose is to provide volumes for other services.
### user-volumes
Provides user accessible persistent storage directories, used by console service:
```
/home
/opt
```
### container-data-volumes
Provides docker storage directory, used by console service (and, indirectly, by docker)
```
/var/lib/docker
```
### command-volumes
Provides necessary command binaries (read-only), used by system services:
```
/usr/bin/docker-containerd.dist
/usr/bin/docker-containerd-shim.dist
/usr/bin/docker-runc.dist
/usr/bin/docker.dist
/usr/bin/dockerlaunch
/usr/bin/user-docker
/usr/bin/system-docker
/sbin/poweroff
/sbin/reboot
/sbin/halt
/sbin/shutdown
/usr/bin/respawn
/usr/bin/ros
/usr/bin/cloud-init
/usr/sbin/netconf
/usr/sbin/wait-for-docker
/usr/bin/switch-console
```
### system-volumes
Provides necessary persistent directories, used by system services:
```
/host/dev
/etc/docker
/etc/hosts
/etc/resolv.conf
/etc/ssl/certs/ca-certificates.crt.rancher
/etc/selinux
/lib/firmware
/lib/modules
/run
/usr/share/ros
/var/lib/rancher/cache
/var/lib/rancher/conf
/var/lib/rancher
/var/log
/var/run
```
### all-volumes
Combines all of the above, used by the console service.