mirror of
https://github.com/rancher/rancher-docs.git
synced 2026-09-25 04:28:15 +00:00
Rewrite custom-kernels and custom-rancheros-iso
This commit is contained in:
niusmallnan
Denise
@@ -25,6 +25,8 @@ VMWare | 1280MB (rancheros.iso) <br> 2048MB (rancheros-vmware.iso)
|
||||
GCE | 1280MB
|
||||
AWS | 1.7GB
|
||||
|
||||
You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)
|
||||
|
||||
### How this works
|
||||
|
||||
Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker**, the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd`, and can be used to launch [additional system services](installation/system-services/adding-system-services/).
|
||||
|
||||
@@ -3,86 +3,78 @@ title: Custom Kernels
|
||||
weight: 181
|
||||
---
|
||||
|
||||
### Kernel version in RancherOS
|
||||
|
||||
RancherOS basically uses the standard Linux kernel, but we maintain a kernel config ourselves. Due to various feature support and security fixes, we are constantly updating the kernel version.
|
||||
|
||||
RancherOS | Kernel
|
||||
--------- | ------
|
||||
<=v0.7.1 | 4.4.x
|
||||
<=v1.3.0 | 4.9.x
|
||||
>=v1.4.0 | 4.14.x
|
||||
|
||||
### Building and Packaging a Kernel to be used in RancherOS
|
||||
|
||||
We build the kernel for RancherOS at the [os-kernel repository](https://github.com/rancher/os-kernel). You can use this repository to help package your own custom kernel to be used in RancherOS.
|
||||
|
||||
Create a clone of the [os-kernel](https://github.com/rancher/os-kernel) repository to your local machine using `git clone`.
|
||||
|
||||
1. Create a clone of the [os-kernel](https://github.com/rancher/os-kernel) repository to your local machine using `git clone`.
|
||||
```
|
||||
$ git clone https://github.com/rancher/os-kernel.git
|
||||
```
|
||||
2. In the `./Dockerfile.dapper` file, update the `KERNEL_TAG`, `KERNEL_VERSION`, `KERNEL_URL` and `KERNEL_SHA1`. `KERNEL_URL` points to Linux kernel sources archive, packaged as `.tar.gz` or `.tar.xz`. `KERNEL_SHA1` is the `SHA1` sum of the kernel sources archive.
|
||||
`./Dockerfile.dapper` file
|
||||
```
|
||||
$ git clone https://github.com/rancher/os-kernel.git
|
||||
```
|
||||
|
||||
```bash
|
||||
########## Kernel version Configuration #############################
|
||||
ENV KERNEL_TAG=v4.8.7
|
||||
ENV KERNEL_VERSION=4.8.7-rancher
|
||||
ENV KERNEL_SHA1=5c10724a0e7e97b72046be841df0c69c6e2a03c2
|
||||
ENV KERNEL_URL=https://github.com/rancher/linux/archive/${KERNEL_TAG}.tar.gz
|
||||
```
|
||||
3. After you've replaced the `KERNEL_*` values, run `make` in the root `os-kernel` directory. After the build is completed, a `./dist/kernel` directory will be created with the freshly built kernel tarball and headers.
|
||||
```
|
||||
$ make
|
||||
...snip...
|
||||
--- 4.8.7-rancher Kernel prepared for RancherOS
|
||||
./dist/kernel/extra-linux-4.8.7-rancher-x86.tar.gz
|
||||
./dist/kernel/build-linux-4.8.7-rancher-x86.tar.gz
|
||||
./dist/kernel/linux-4.8.7-rancher-x86.tar.gz
|
||||
./dist/kernel/config
|
||||
If you want to build kernel v4.14.53, you can refer to the following command. After the build is completed, a `./dist/kernel` directory will be created with the freshly built kernel tarball and headers.
|
||||
|
||||
Images ready to push:
|
||||
rancher/os-extras:4.8.7-rancher
|
||||
rancher/os-headers:4.8.7-rancher
|
||||
```
|
||||
```
|
||||
$ git tag v4.14.53-rancher
|
||||
$ KERNEL_TAG=4.14.53 make release
|
||||
...snip...
|
||||
./dist/kernel/extra-linux-4.14.53-rancher-x86.tar.gz
|
||||
./dist/kernel/build-linux-4.14.53-rancher-x86.tar.gz
|
||||
./dist/kernel/linux-4.14.53-rancher-x86.tar.gz
|
||||
./dist/kernel/config
|
||||
...snip...
|
||||
Images ready to push:
|
||||
rancher/os-extras:4.14.53-rancher
|
||||
rancher/os-headers:4.14.53-rancher
|
||||
```
|
||||
For some users who need a custom kernel, the following information is very useful to you:
|
||||
|
||||
Now you need to either upload the `./dist/kernel/linux-4.8.7-rancher-x86.tar.gz` file to somewhere, or copy that file into your clone of the `rancher/os` repo, as `assets/kernel.tar.gz`.
|
||||
1. The modules defined in `modules.list` will be packaged into the built-in modules.
|
||||
2. The modules defined in `modules-extra.list` will be packaged into the extra modules.
|
||||
3. You can modify `config/kernel-config` to build the kernel modules you need.
|
||||
4. You can add your patches in the `patches` directory, and `os-kernel` will update these patches after downloading the kernel source.
|
||||
|
||||
Now you need to either upload the `./dist/kernel/linux-4.14.53-rancher-x86.tar.gz` file to somewhere, or copy that file into your clone of the `rancher/os` repo, as `assets/kernel.tar.gz`.
|
||||
|
||||
The `build-<name>.tar.gz` and `extra-<name>.tar.gz` files are used to build the `rancher/os-extras` and `rancher/os-headers` images for your RancherOS release - which you will need to tag them with a different organisation name, push them to a registry, and create custom service.yml files.
|
||||
|
||||
Your kernel should be packaged and published as a set of files of the following format:
|
||||
|
||||
1. `<kernel-name-and-version>.tar.gz` is the one KERNEL_URL in `rancher/os` should point to. It contains the kernel binary, core modules and firmware.
|
||||
|
||||
2. `build-<kernel-name-and-version>.tar.gz` contains build headers to build additional modules: it is a subset of the kernel sources tarball. These files will be installed into `/usr/src/<os-kernel-tag>` using the `kernel-headers-system-docker` and `kernel-headers` services.
|
||||
|
||||
3. `extra-<kernel-name-and-version>.tar.gz` contains extra modules and firmware for your kernel and should be built into a `kernel-extras` service.
|
||||
|
||||
### Building a RancherOS release using the Packaged kernel files.
|
||||
|
||||
By default, RancherOS ships with the kernel provided by the [os-kernel repository](https://github.com/rancher/os-kernel). Swapping out the default kernel can by done by [building your own custom RancherOS ISO]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).
|
||||
1. Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
|
||||
```
|
||||
$ git clone https://github.com/rancher/os.git
|
||||
```
|
||||
2. In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` will need to be updated. Using your favorite editor, replace the appropriate `KERNEL_URL` value with a URL of your compiled custom kernel tarball. Ideally, the URL will use `HTTPS`.
|
||||
`Dockerfile.dapper` file
|
||||
```
|
||||
# Update the URL to your own custom kernel tarball
|
||||
ARG KERNEL_URL_amd64=https://github.com/rancher/os-kernel/releases/download/Ubuntu-4.4.0-23.41-rancher/linux-4.4.10-rancher-x86.tar.gz
|
||||
ARG KERNEL_URL_arm64=https://github.com/imikushin/os-kernel/releases/download/Estuary-4.1.18-arm64-3/linux-4.1.18-arm64.tar.gz
|
||||
```
|
||||
|
||||
Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
|
||||
|
||||
```
|
||||
$ git clone https://github.com/rancher/os.git
|
||||
```
|
||||
|
||||
In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` will need to be updated. Using your favorite editor, replace the appropriate `KERNEL_URL` value with a URL of your compiled custom kernel tarball. Ideally, the URL will use `HTTPS`.
|
||||
|
||||
```
|
||||
# Update the URL to your own custom kernel tarball
|
||||
ARG KERNEL_VERSION_amd64=4.14.63-rancher
|
||||
ARG KERNEL_URL_amd64=https://link/xxxx
|
||||
```
|
||||
|
||||
After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).
|
||||
|
||||
> **Note:** `KERNEL_URL` settings should point to a Linux kernel, compiled and packaged in a specific way. You can fork [os-kernel repository](https://github.com/rancher/os-kernel) to package your own kernel.
|
||||
|
||||
Your kernel should be packaged and published as a set of files of the following format:
|
||||
|
||||
`<kernel-name-and-version>.tar.gz` is the one KERNEL_URL should point to. It contains the kernel binary, core modules and firmware:
|
||||
|
||||
```
|
||||
boot/
|
||||
vmlinuz-<kernel-version>
|
||||
lib/
|
||||
modules/
|
||||
<kernel-version>/
|
||||
...
|
||||
firmware/
|
||||
...
|
||||
```
|
||||
|
||||
`build.tar.gz` contains build headers to build additional modules: it is a subset of the kernel sources tarball. These files will be installed into `/usr/src/<os-kernel-tag>` using the `kernel-headers-system-docker` and `kernel-headers` services.
|
||||
|
||||
`extra.tar.gz` contains extra modules and firmware for your kernel and should be built into a `kernel-extras` service:
|
||||
|
||||
```
|
||||
lib/
|
||||
modules/
|
||||
<kernel-version>/
|
||||
...
|
||||
firmware/
|
||||
...
|
||||
```
|
||||
3. After you've replaced the URL with your custom kernel, you can follow the steps in [building your own custom RancherOS ISO]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/).
|
||||
|
||||
@@ -5,79 +5,70 @@ weight: 182
|
||||
|
||||
It's easy to build your own RancherOS ISO.
|
||||
|
||||
1. Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
|
||||
```
|
||||
$ git clone https://github.com/rancher/os.git
|
||||
```
|
||||
2. In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` can be updated to use [custom kernels]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-kernels).
|
||||
3. After you've saved your edits, run `make` in the root directory. After the build has completed, a `./dist/artifacts` directory will be created with the custom built RancherOS release files.
|
||||
Build Requirements: `bash`, `make`, `docker` (Docker version >= 1.10.3)
|
||||
```
|
||||
$ make
|
||||
$ cd dist/artifacts
|
||||
$ ls
|
||||
initrd rancheros.iso
|
||||
iso-checksums.txt vmlinuz
|
||||
```
|
||||
Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
|
||||
|
||||
```
|
||||
$ git clone https://github.com/rancher/os.git
|
||||
```
|
||||
|
||||
In the root of the repository, the "General Configuration" section of `Dockerfile.dapper` can be updated to use [custom kernels]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-kernels).
|
||||
After you've saved your edits, run `make` in the root directory. After the build has completed, a `./dist/artifacts` directory will be created with the custom built RancherOS release files.
|
||||
Build Requirements: `bash`, `make`, `docker` (Docker version >= 1.10.3)
|
||||
|
||||
```
|
||||
$ make
|
||||
$ cd dist/artifacts
|
||||
$ ls
|
||||
initrd rancheros.iso
|
||||
iso-checksums.txt vmlinuz
|
||||
```
|
||||
|
||||
If you need a compressed ISO, you can run this command:
|
||||
|
||||
```
|
||||
$ INTEGRATION_TESTS=0 make release
|
||||
```
|
||||
|
||||
The `rancheros.iso` is ready to be used to [boot RancherOS from ISO]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/boot-from-iso/) or [launch RancherOS using Docker Machine]({{< baseurl >}}/os/v1.x/en/installation/running-rancheros/workstation/docker-machine).
|
||||
|
||||
|
||||
### Creating a GCE Image Archive
|
||||
|
||||
You can build the [GCE image archive](https://cloud.google.com/compute/docs/tutorials/building-images) using [Packer](https://www.packer.io/). You will need Packer, QEMU and GNU tar installed.
|
||||
|
||||
First, create `gce-qemu.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"builders":
|
||||
[
|
||||
{
|
||||
"type": "qemu",
|
||||
"name": "qemu-googlecompute",
|
||||
"iso_url": "https://github.com/rancherio/os/releases/download/<RancherOS-Version>/rancheros.iso",
|
||||
"iso_checksum": "<rancheros.iso-MD5-hash>",
|
||||
"iso_checksum_type": "md5",
|
||||
"ssh_wait_timeout": "360s",
|
||||
"disk_size": 10000,
|
||||
"format": "raw",
|
||||
"headless": true,
|
||||
"accelerator": "none",
|
||||
"ssh_host_port_min": 2225,
|
||||
"ssh_host_port_max": 2229,
|
||||
"ssh_username": "rancher",
|
||||
"ssh_password": "rancher",
|
||||
"ssh_port": 22,
|
||||
"net_device": "virtio-net",
|
||||
"disk_interface": "scsi",
|
||||
"qemuargs": [
|
||||
["-m", "1024M"], ["-nographic"], ["-display", "none"]
|
||||
]
|
||||
}
|
||||
],
|
||||
"provisioners": [
|
||||
{
|
||||
"type":"shell",
|
||||
"script": "../scripts/install2disk"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
NOTE: For faster builds You can use `"kvm"` as the `accelerator` field value if you have KVM, but that's optional.
|
||||
|
||||
Run:
|
||||
Create a clone of the main [RancherOS repository](https://github.com/rancher/os) to your local machine with a `git clone`.
|
||||
|
||||
```
|
||||
$ packer build gce-qemu.json
|
||||
$ git clone https://github.com/rancher/os-packer.git
|
||||
```
|
||||
|
||||
Packer places its output into `output-qemu-googlecompute/packer-qemu-googlecompute` - it's a raw VM disk image. Now you just need to name it `disk.raw` and package it as sparse .tar.gz:
|
||||
GCE supports KVM virtualization, and we use `packer` to build KVM images. Before building, you need to verify that the host can support KVM.
|
||||
If you want to build GCE image based on RancherOS v1.4.0, you can run this command:
|
||||
|
||||
```
|
||||
$ mv output-qemu-googlecompute/packer-qemu-googlecompute disk.raw
|
||||
$ tar -czSf rancheros-<RancherOS-Version>.tar.gz disk.raw
|
||||
RANCHEROS_VERSION=v1.4.0 make build-gce
|
||||
```
|
||||
|
||||
NOTE: the last command should be using GNU tar. It might be named `gtar` on your system.
|
||||
### Custom build cases
|
||||
|
||||
#### Reduce memory requirements
|
||||
|
||||
With the changes of the kernel and built docker, RancherOS booting requires more memory, please refer to [Memory Requirements]({{< baseurl >}}/os/v1.x/en/#hardware-requirements).
|
||||
|
||||
By customizing the ISO, you can reduce the memory usage on boot. The easiest way is to downgrade the built-in docker version, because docker takes up a lot of space.
|
||||
This can effectively reduce the memory required to decompress the initrd on boot, using docker 17.03 is a good choice:
|
||||
|
||||
```
|
||||
# update os-config.tpl.yml in rancher/os
|
||||
hostname: {{.HOSTNAME_DEFAULT}}
|
||||
{{if eq "amd64" .ARCH -}}
|
||||
docker:
|
||||
- engine: docker-18.03.1-ce
|
||||
+ engine: docker-17.03.2-ce
|
||||
{{else -}}
|
||||
docker:
|
||||
- engine: docker-18.03.1-ce
|
||||
+ engine: docker-17.03.2-ce
|
||||
{{end -}}
|
||||
...
|
||||
|
||||
# run make
|
||||
$ INTEGRATION_TESTS=0 make release
|
||||
```
|
||||
|
||||
@@ -25,6 +25,8 @@ VMWare | 1280MB (rancheros.iso) <br> 2048MB (rancheros-vmware.iso)
|
||||
GCE | 1280MB
|
||||
AWS | 1.7GB
|
||||
|
||||
You can adjust memory requirements by custom building RancherOS, please refer to [reduce-memory-requirements]({{< baseurl >}}/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/#reduce-memory-requirements)
|
||||
|
||||
### How this works
|
||||
|
||||
Everything in RancherOS is a Docker container. We accomplish this by launching two instances of Docker. One is what we call **System Docker**, the first process on the system. All other system services, like `ntpd`, `syslog`, and `console`, are running in Docker containers. System Docker replaces traditional init systems like `systemd`, and can be used to launch [additional system services]({{< baseurl >}}/os/v1.x/en/installation/system-services/adding-system-services/).
|
||||
|
||||
Reference in New Issue
Block a user