DOCSEARCHbyAlgolia
Submit Docs

RKE2 Documentation

repository·master·Indexed 25 days ago

https://github.com/rancher/rke2

A security-focused, fully conformant Kubernetes distribution designed for high-compliance environments, such as the U.S. Federal Government sector. Documentation covers installation, configuration via YAML or CLI, building from source, and tools for overriding core Kubernetes images and kubelet binaries.

Tokens
19.4K
Snippets
28
Records
109
Agent score
81%

What's inside RKE2

  1. Override RKE2 images and kubelet binaries

    master

    This tool uses a Python script to generate configuration files and extract binaries from a Kubernetes release manifest YAML. It allows you to override the default images and binaries for core Kubernetes components, including:

    • coredns
    • etcd
    • kube-apiserver
    • kube-controller-manager
    • kube-proxy
    • kube-scheduler
    • kubelet
    • metrics-server
    • pause

    Note that components like the Helm Controller, Calico+Flannel CNI, and Nginx Ingress are not overridden by this process.

    Requirements

    • RKE2 Version: v1.18.13+rke2r1 or newer (must support image/kubelet override).
    • Python: Python 3.
    • Release Format: Manifests must follow the EKS Distro release format.
    • AWS ECR Access: Required if the replacement RKE2 images are stored in ECR (via AWS CLI IAM keys or EC2 instance role).

  2. How RKE2 handles manifest updates during binary restart

    master

    When the rke2 binary restarts after an upgrade, it performs the following lifecycle steps:

    1. Extraction: It extracts manifests from the runtime image into /var/lib/rancher/rke2/server/manifests.
    2. Replacement: It replaces existing manifests from the previous version with the new ones.
    3. Deployment: The deployment controller loops over these manifests and applies them to the cluster as Addon resources.

    Exceptions to automatic deployment:

    • Disabled Components: If a component was explicitly disabled (e.g., via the --disable CLI flag), the controller attempts to uninstall it and removes the manifest.
    • Skipped Components: If a manifest has the .skip suffix (e.g., component.yaml.skip), the controller ignores it and does not attempt an upgrade.

  3. Understand RKE2 Helm Charts

    master

    RKE2 consumes several core components via Helm Charts, which are installed in the cluster by the helm-controller (part of the rke2 server binary).

    Components managed via Helm Charts include:

    • coredns
    • ingress-nginx
    • metrics-server
    • kube-proxy (up to v1.21)
    • All CNI plugins

    These charts are maintained in the rancher/rke2-charts repository.

  4. Manage Cloud Controller Manager (CCM) behavior in RKE2

    master

    RKE2's resource usage and controller behavior depend on how the Cloud Controller Manager (CCM) and ServiceLB are configured:

    • To disable the CCM entirely: Use the --disable-cloud-controller flag. This disables the cloud-node and cloud-node-lifecycle controllers. If both the cloud-controller and ServiceLB are disabled, the cloud-controller-manager is not run at all.
    • To enable ServiceLB: Use the --enable-servicelb flag. This prevents --disable=servicelb from being passed to the underlying K3s engine and enables the CCM's service controller.
    • Resource Optimization: RKE2 uses fewer resources when ServiceLB is disabled because several core controllers are not started unconditionally.

  5. When to use Issues vs Pull Requests for architecture

    master

    Decide whether to open an Issue or a Pull Request based on the goal of the communication:

    Use an Issue when:

    • You need context about a decision.
    • You have a question.
    • You have a suggestion that might trigger the need for a new decision.
    • You believe additional context might change an existing decision.

    Use a Pull Request when:

    • You are providing additional context for a decision.
    • A decision has been made but no ADR currently exists for it.
    • You are formalizing a decision that was previously discussed in a design meeting.

  6. Compare RKE2 installation methods: RPM vs Tarball

    master

    RKE2 supports two primary installation methods on SUSE distributions, which differ in binary location and SELinux handling:

    FeatureTarball Method (Default)RPM Method
    Binary Path/opt/usr
    SELinuxNot enabled by defaultEnabled via rke2-selinux
    TriggerDefault behaviorSet RKE2_INSTALL_METHOD=rpm

    Important Constraints:

    • The installation script prevents switching from RPM to tarball (or vice versa) after the initial installation.
    • If using the tarball method, SELinux must be enabled manually.

  7. Supported installation methods for RKE2

    master

    RKE2 provides different installation methods depending on the target platform:

    1. CentOS 7/8: Supports direct installation via RPMs.
    2. Other Platforms: For platforms other than CentOS 7/8, the supported installation method is a combination of using the tarball installation method and an SELinux policy RPM (where SELinux support is required).

    RPMs are published to rpm.rancher.io or rpm-testing.rancher.io.

  8. Understand RKE2 Developer Documentation and Diagrams

    master

    Developer documentation is located in the developer-docs/ directory of this repository. These files are intended for contributors and focus on internal processes and technical details.

    Diagrams: Technical diagrams within these docs use Mermaid syntax inside fenced code blocks. To view or edit them, use a markdown previewer that supports GitHub-style embedded Mermaid diagrams or use the Mermaid live editor.

  9. Access RKE2 Architectural Decision Records (ADRs)

    master
    Architectural Decision Records (ADRs) are maintained to document the context, arguments, and decisions regarding RKE2's software architecture and processes. These records allow developers to understand the rationale behind previous technical decisions. ADRs are located in the docs/adrs/ directory.

  10. Understand the security-responder data collection

    master

    The security-responder client collects specific cluster metadata to assist with security visibility and project maintenance. The data collected is non-personally identifiable and includes:

    • kubernetesVersion (within extraTagInfo)
    • clusteruuid (within extraTagInfo)
    • serverNodeCount (within extraFieldInfo)
    • agentNodeCount (within extraFieldInfo)
    • cni-plugin (within extraFieldInfo)
    • ingress-controller (within extraFieldInfo)
    • os (within extraFieldInfo)
    • selinux (within extraFieldInfo)

    The clusteruuid is the UUID of the kube-system namespace and is used to differentiate between deployments without exposing privacy-sensitive information.

    {
  "appVersion": "v1.31.6+rke2r1",
  "extraTagInfo": {
    "kubernetesVersion": "v1.31.6",
    "clusteruuid": "53741f60-f208-48fc-ae81-8a969510a598"
  },
  "extraFieldInfo": {
    "serverNodeCount": 3,
    "agentNodeCount": 2,
    "cni-plugin": "flannel",
    "ingress-controller": "rke2-ingress-nginx",
    "os": "ubuntu",
    "selinux": "enabled"
  }
}

  11. Traefik Ingress Controller support in RKE2

    master

    RKE2 supports Traefik as a packaged ingress controller. To maintain parity with the default ingress-nginx configuration (since RKE2 lacks a default LoadBalancer controller), Traefik is deployed as a Daemonset combined with a ClusterIP Service.

    Note that RKE2 uses mirrored upstream Traefik images; it does not provide or support custom-rebuilt hardened Traefik images.

  12. How Architectural Decision Records (ADRs) work in RKE2

    master

    RKE2 uses Architectural Decision Records (ADRs) to document the arguments and context behind changes to process or software architecture. Unlike traditional numbered ADR models, RKE2 uses a version-controlled approach where files have contextual names and history is managed via the source code management system (Git).

    Status Types

    ADRs follow a simplified status model:

    • accepted: The decision is finalized and in effect.
    • rejected: The proposed decision was not adopted.
    • superseded: The decision is no longer current because it has been replaced by a newer decision. When an ADR is superseded, its status should be updated to superseded by [link to new doc], and both the old and new ADRs should provide context as to why the change occurred.