diff --git a/content/os/v1.x/en/_index.md b/content/os/v1.x/en/_index.md index a94f6c4269f..2704adbe6f5 100644 --- a/content/os/v1.x/en/_index.md +++ b/content/os/v1.x/en/_index.md @@ -25,6 +25,8 @@ VMWare | 1280MB (rancheros.iso)
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/). diff --git a/content/os/v1.x/en/installation/custom-builds/custom-kernels/_index.md b/content/os/v1.x/en/installation/custom-builds/custom-kernels/_index.md index cf6a71c13fd..8a7ff668a11 100644 --- a/content/os/v1.x/en/installation/custom-builds/custom-kernels/_index.md +++ b/content/os/v1.x/en/installation/custom-builds/custom-kernels/_index.md @@ -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-.tar.gz` and `extra-.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. `.tar.gz` is the one KERNEL_URL in `rancher/os` should point to. It contains the kernel binary, core modules and firmware. + +2. `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/` using the `kernel-headers-system-docker` and `kernel-headers` services. + +3. `extra-.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: - - `.tar.gz` is the one KERNEL_URL should point to. It contains the kernel binary, core modules and firmware: - - ``` - boot/ - vmlinuz- - lib/ - modules/ - / - ... - 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/` 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/ - / - ... - 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/). diff --git a/content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md b/content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md index f5fb5c07359..430631a20df 100644 --- a/content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md +++ b/content/os/v1.x/en/installation/custom-builds/custom-rancheros-iso/_index.md @@ -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.iso", - "iso_checksum": "", - "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-.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 +``` diff --git a/content/os/v1.x/en/overview/_index.md b/content/os/v1.x/en/overview/_index.md index 6992b13feb0..dfd1b8b3a76 100644 --- a/content/os/v1.x/en/overview/_index.md +++ b/content/os/v1.x/en/overview/_index.md @@ -25,6 +25,8 @@ VMWare | 1280MB (rancheros.iso)
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/).