Cluster Creation with K8Rngr

By Raj Marni. March 28, 2025. Revised. Version: 0.0.06

A detailed example below shows how C128 – K8Rngr automates the entire K3s cluster creation process on AWS EC2 or DigitalOcean Droplets, from the user’s “Create Cluster” click to a fully functional Kubernetes environment. By integrating with AccessPoint for security checks, leveraging provider APIs for resource provisioning, and installing K3s with consistent configurations, K8Rngr simplifies the multi-cloud cluster lifecycle—ensuring k8or Orbit’s ephemeral or persistent clusters remain standardized, secure, and easy to manage.

1. Prerequisites & Setup

  1. Orbit Plane Credentials

    • K8Rngr (C128) has been installed and configured in the orbit plane using Component C124.

    • The user (DevOps engineer or admin) has sufficient permissions to create clusters via K8Rngr.

    • AccessPoint (C52) is set up so that any requests from K8Rngr to external cloud providers must pass the necessary authentication and authorization checks.

  2. Cloud Provider Credentials

    • AWS: The user has an AWS access key and secret key or an IAM role that grants the required permissions (EC2, VPC, IAM, etc.).

    • DigitalOcean: The user has a Personal Access Token with read/write privileges to create droplets, networking rules, etc.

  3. K8Rngr UI or API

    • The user can access K8Rngr’s web interface (or the K8Rngr CLI/API) via the orbit-plane Portal.

    • The orbit-plane IAM ensures the user is authorized to perform cluster-creation actions in K8Rngr.

2. Initiating Cluster Creation

2.1 User Chooses Cloud Provider & Node Configuration

  1. K8Rngr Dashboard

    • The user logs into the orbit-plane Portal (OpsBoard) and navigates to K8Rngr (C128), selecting “Create Cluster”.

  2. Select Provider

    • The user picks either “Amazon EC2” or “DigitalOcean” from a list of supported providers.

    • Alternatively, the user might see “AWS” or “DO” as an environment option in a custom orbit-plane UI, which then instructs K8Rngr accordingly.

  3. Node Settings

    • For AWS:

      • The user selects a region (e.g., us-east-1), instance type (e.g., t3.medium), desired node count (e.g., 3 for a small HA cluster).

      • They can specify VPC or subnet details, or let K8Rngr create a new VPC.

    • For DigitalOcean:

      • The user picks a region (e.g., NYC3), a Droplet size (e.g., s-2vcpu-4gb), and node count.

      • Optionally configures SSH keys or firewall rules.

  4. K3s Parameters

    • The user can set K3s cluster-level configs (e.g., enabling certain add-ons, specifying a cluster name like dev-k3s).

  5. Credential Input

    • If not already stored, the user enters or selects stored AWS credentials or DigitalOcean token.

    • K8Rngr fetches or uses these credentials to manage resources on the chosen provider.

2.2 AccessPoint Authorization

  1. Internal Request

    • C128 forms a provisioning request: “Create new K3s cluster with these specs”.

    • This request is routed through AccessPoint (C52), which checks that the user’s token or role is valid for “cluster creation”.

  2. Allowed or Denied

    • If authorized, AccessPoint passes the request to the K8Rngr’s provisioning logic. If not, an error is returned, and the user sees an “Access denied” message.

3. Cloud Resource Provisioning

3.1 AWS Example

  1. VPC & Networking

    • C128 calls the AWS API (e.g., via the AWS SDK). If the user chose “Auto VPC”, K8Rngr creates a new VPC, subnets, an Internet gateway, and security groups.

    • If the user selected an existing VPC, K8Rngr references that.

  2. EC2 Instances

    • C128 requests 3 (or however many) EC2 instances of type t3.medium in the chosen region.

    • It sets up user data scripts or cloud-init to install K3s once the instance is running.

  3. Security Groups

    • C128 configures a security group allowing inbound traffic for K3s ports (e.g., 6443 for the API server, node ports if required) and SSH if needed.

  4. IAM Roles

    • Optionally, if the user set advanced settings, C 128 can attach an IAM role to the instances so they can pull images from ECR or access S3 logs.

3.2 DigitalOcean Example

  1. Droplet Creation

    • C128 calls the DigitalOcean API with the user’s token, specifying droplet size (e.g., s-2vcpu-4gb), region (NYC3), and count (e.g., 3).

    • It may pass a custom cloud-init script that installs K3s and sets up node labels, etc.

  2. Networking

    • If private networking is enabled, K8Rngr ensures the droplets are in the same private network for cluster traffic.

    • Firewall rules might be configured to allow inbound K3s API traffic from known sources.

  3. SSH Keys

    • K8Rngr can associate user-specified SSH keys so the user can log in if needed, or it can auto-generate ephemeral keys.

4. K3s Installation & Configuration

  1. K3s Bootstrapping

    • Once the VMs or droplets are up, K8Rngr’s provisioning engine runs an install script or containerized process on the first node to initialize K3s as the control plane.

    • It obtains a K3s token or uses a shared secret for the cluster.

  2. Joining Worker Nodes

    • Additional nodes use the same script/secret to join the cluster, connecting to the K3s server node.

    • C128 logs each node’s status, ensuring they appear in the final cluster view.

  3. Default Add-ons

    • C128 might apply base manifests: e.g., an ingress controller, metrics server, or other standard services depends on organization needs.

    • The user can specify additional Helm charts or configurations to be deployed automatically.

  4. Validation Checks

    • C128 verifies that each node is “Ready”, the K3s API is reachable, and that the cluster passes basic health checks.

    • If any node fails, it logs an error and can optionally attempt re-provisioning.

5. Post-Provisioning & Lifecycle

  1. Cluster Registered

    • Once the cluster is healthy, K8Rngr adds it to its list of managed clusters in the orbit-plane.

    • The user sees “Cluster dev-k3s created successfully” in the C128 UI or the orbit-plane Portal.

  2. Monitoring & Logs

    • C128 configures or references the orbit-plane’s monitoring stack (e.g., InsightHub) to gather cluster metrics (CPU, memory) and logs.

    • The user can see real-time stats or alerts in the orbit-plane’s dashboards.

  3. Scaling & Upgrades

    • The user can later scale from 3 to 5 nodes, or perform a K3s version upgrade. K8Rngr orchestrates these changes by calling the same provider APIs (to create new instances) and updating node software.

    • All changes again pass through AccessPoint for authentication/authorization.

  4. Destruction / Cleanup

    • If the cluster is no longer needed, the user chooses “Delete Cluster”. C128 tears down VMs/droplets, releases networking resources, and updates the orbit-plane’s records to reflect the cluster’s removal.

6. Error Handling & Troubleshooting

  1. Provisioning Failures

    • If AWS returns an error (e.g., insufficient permissions, region capacity issues) or DigitalOcean denies the request (invalid token), K8Rngr logs the failure.

    • The user sees an error message in the UI, possibly with a hint to fix credentials or use a different region.

  2. Node Join Failures

    • If a node can’t join K3s (firewall misconfiguration, token mismatch), K8Rngr logs partial success and might auto-retry or prompt the user to fix networking.

  3. Rollback or Partial Cleanup

    • If provisioning is partially complete, K8Rngr can destroy leftover resources (unused VMs, incomplete load balancers) to avoid incurring costs or leaving orphaned resources.

  4. AccessPoint Denials

    • If the request is unauthorized (e.g., the user tries to create a production cluster without the correct role), the AccessPoint denies it. The user sees “Access Denied”, and no resources are created.

7. Summary of the Example Flow

  1. User chooses “Create Cluster” in K8Rngr UI.

  2. User picks AWS or DO, sets node count and size, and references credentials.

  3. K8Rngr forms a cluster creation request, passes it through AccessPoint for security checks.

  4. K8Rngr calls the provider’s API to create VMs or droplets.

  5. K8Rngr installs K3s on the newly provisioned machines, forming a cluster.

  6. K8Rngr verifies cluster health, logs success, and displays the new cluster in the orbit-plane.

  7. User can now manage, scale, or tear down the cluster through K8Rngr’s interface.

8. Benefits & Impact

  • Automated Multi-Cloud: One consistent workflow to spin up K3s on AWS or DigitalOcean (or other providers).

  • Security & Governance: All provisioning requests pass through AccessPoint, ensuring only authorized users can create or modify clusters.

  • Scalability & Standardization: Each new cluster is configured with consistent best practices, networking, and RBAC policies.

  • Reduced Manual Errors: The user doesn’t have to manually run cloud CLI commands or K3s installers—C128 K8Rngr does it reliably.

PreviousAWS Controllers for k8orNextCluster Bootstrap with Argo CD

Last updated