Skip to content

quickstart.md

Latest commit

 

History

History
255 lines (211 loc) · 11.3 KB

quickstart.md

File metadata and controls

255 lines (211 loc) · 11.3 KB
Raw

Quickstart

Overview

This guide demonstrates how to use RMK to prepare the structure of a new project, create a local cluster based on K3D, and deploy your first application (Nginx) using Helmfile releases.

All of this will be done in just 5 steps.

Prerequisites

This example assumes the project (tenant) name is rmk-test, the current Git branch is develop, the configured Git remote is origin.

Steps

  1. Generate the project structure, the project.yaml file, and SOPS Age keys:

    rmk project generate --scope rmk-test --environment "develop.root-domain=localhost" --create-sops-age-keys

    The default scope is deps, it is added unconditionally during the project generation process, no need to specify it explicitly.

    Example output ```text 2025-01-29T14:20:02.954+0100 INFO file /home/user/rmk-test/etc/deps/develop/values/aws-cluster.yaml.gotmpl generated 2025-01-29T14:20:02.956+0100 INFO file /home/user/rmk-test/etc/deps/develop/values/azure-cluster.yaml.gotmpl generated 2025-01-29T14:20:02.956+0100 INFO file /home/user/rmk-test/etc/deps/develop/values/gcp-cluster.yaml.gotmpl generated 2025-01-29T14:20:02.957+0100 INFO file /home/user/rmk-test/etc/deps/develop/globals.yaml.gotmpl generated 2025-01-29T14:20:02.957+0100 INFO file /home/user/rmk-test/etc/deps/develop/releases.yaml generated 2025-01-29T14:20:02.957+0100 INFO file /home/user/rmk-test/etc/deps/develop/secrets/.spec.yaml.gotmpl generated 2025-01-29T14:20:02.957+0100 INFO file /home/user/rmk-test/etc/deps/develop/secrets/.sops.yaml generated 2025-01-29T14:20:02.957+0100 INFO file /home/user/rmk-test/etc/rmk-test/develop/globals.yaml.gotmpl generated 2025-01-29T14:20:02.958+0100 INFO file /home/user/rmk-test/etc/rmk-test/develop/releases.yaml generated 2025-01-29T14:20:02.958+0100 INFO file /home/user/rmk-test/etc/rmk-test/develop/secrets/.spec.yaml.gotmpl generated 2025-01-29T14:20:02.958+0100 INFO file /home/user/rmk-test/etc/rmk-test/develop/values/rmk-test-app.yaml.gotmpl generated 2025-01-29T14:20:02.958+0100 INFO file /home/user/rmk-test/etc/rmk-test/develop/secrets/.sops.yaml generated 2025-01-29T14:20:02.958+0100 INFO file /home/user/rmk-test/.gitignore generated 2025-01-29T14:20:02.959+0100 INFO file /home/user/rmk-test/helmfile.yaml.gotmpl generated 2025-01-29T14:20:02.959+0100 INFO file /home/user/rmk-test/README.md generated 2025-01-29T14:20:02.986+0100 INFO generate age key for scope: deps 2025-01-29T14:20:02.986+0100 INFO update SOPS config file: /home/user/rmk-test/etc/deps/develop/secrets/.sops.yaml 2025-01-29T14:20:03.000+0100 INFO generate age key for scope: rmk-test 2025-01-29T14:20:03.001+0100 INFO update SOPS config file: /home/user/rmk-test/etc/rmk-test/develop/secrets/.sops.yaml ```

  2. Initialize RMK configuration for the repository:

    rmk config init

    The default cluster provider is k3d.

    Example output ```text 2025-01-29T14:22:44.548+0100 INFO loaded config file by path: /home/user/.rmk/config/rmk-test-develop.yaml 2025-01-29T14:22:44.550+0100 INFO RMK will use values for develop environment 2025-01-29T14:22:44.553+0100 INFO starting package download: cluster-deps.bootstrap.infra-v0.1.0 2025-01-29T14:22:45.790+0100 INFO downloaded: cluster-deps.bootstrap.infra-v0.1.0 2025-01-29T14:22:45.793+0100 INFO starting package download: helmfile.hooks.infra-v1.29.1 2025-01-29T14:22:46.598+0100 INFO downloaded: helmfile.hooks.infra-v1.29.1 2025-01-29T14:22:46.864+0100 INFO time spent on initialization: 2s ```

  3. Create a local K3D cluster:

    rmk cluster k3d create

    Ensure that Docker is running.

    Example output ```text INFO[0000] Using config file /var/folders/_d/y2s0znsj5l117xk90392xc540000gn/T/k3d-config.51481123.yaml (k3d.io/v1alpha5#simple) INFO[0000] portmapping '8080:80' targets the loadbalancer: defaulting to [servers:*:proxy agents:*:proxy] INFO[0000] portmapping '8443:443' targets the loadbalancer: defaulting to [servers:*:proxy agents:*:proxy] INFO[0000] portmapping '9111:9000' targets the loadbalancer: defaulting to [servers:*:proxy agents:*:proxy] INFO[0000] Prep: Network INFO[0000] Created network 'k3d-rmk-test-develop' INFO[0000] Created image volume k3d-rmk-test-develop-images INFO[0000] Starting new tools node... INFO[0000] Starting node 'k3d-rmk-test-develop-tools' INFO[0001] Creating node 'k3d-rmk-test-develop-server-0' INFO[0001] Creating LoadBalancer 'k3d-rmk-test-develop-serverlb' INFO[0002] Pulling image 'ghcr.io/k3d-io/k3d-proxy:5.7.3' INFO[0015] Using the k3d-tools node to gather environment information INFO[0016] Starting new tools node... INFO[0016] Starting node 'k3d-rmk-test-develop-tools' INFO[0019] Starting cluster 'rmk-test-develop' INFO[0019] Starting servers... INFO[0022] Starting node 'k3d-rmk-test-develop-server-0' INFO[0047] All agents already running. INFO[0047] Starting helpers... INFO[0047] Starting node 'k3d-rmk-test-develop-serverlb' INFO[0053] Injecting records for hostAliases (incl. host.k3d.internal) and for 3 network members into CoreDNS configmap... INFO[0056] Cluster 'rmk-test-develop' created successfully! INFO[0056] You can now use it like this: kubectl cluster-info ```

  4. Generate and encrypt secrets for the Helmfile releases, including Nginx:

    rmk secret manager generate --scope rmk-test --environment develop
rmk secret manager encrypt --scope rmk-test --environment develop
    Example output ```text 2025-01-29T14:19:57.396+0100 INFO generating: /home/user/rmk-test/etc/rmk-test/develop/secrets/rmk-test-app.yaml 2025-01-29T14:19:58.993+0100 INFO encrypting: /home/user/rmk-test/etc/rmk-test/develop/secrets/rmk-test-app.yaml ```

  5. Deploy (sync) all Helmfile releases, including Nginx, to the local K3D cluster:

    rmk release sync
    Example output ```text Release "rmk-test-app" does not exist. Installing it now. NAME: rmk-test-app LAST DEPLOYED: Wed Jan 29 14:23:54 2025 NAMESPACE: rmk-test STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: The app will be available by url: rmk-test-app rmk-test 1 2025-01-29 14:23:54.839083 +0100 CET deployed app-1.6.0 ```

At this stage, the project structure is prepared, and the application (Nginx) has been successfully deployed via Helmfile to the local K3D cluster and is now running.

Verifying the deployment

Verify the application's availability in the Kubernetes cluster:

kubectl --namespace rmk-test port-forward "$(kubectl --namespace rmk-test get pod --output name)" 8080:80
Example output ```text Forwarding from 127.0.0.1:8080 -> 80 Forwarding from [::1]:8080 -> 80 ```

Then, open your browser and visit http://localhost:8080, or run:

open http://localhost:8080

You should see the Nginx welcome page.

Example page

Welcome to nginx!

If you see this page, the nginx web server is successfully installed and working. Further configuration is required.

For online documentation and support please refer to nginx.org.
Commercial support is available at nginx.com.

Thank you for using nginx.

To get list of Kubernetes pods of the rmk-test namespace, run:

kubectl --namespace rmk-test get pod
Example output ```text NAME READY STATUS RESTARTS AGE rmk-test-app-bd588bfd6-ch6n7 1/1 Running 0 3s ```

Collaborating with other team members

To allow other team members to use an existing project, the initial user should commit the changes and push them to the version control system (VCS), e.g., GitHub:

git commit -am "Generate RMK project structure, SOPS secrets, deploy Nginx release."
git push origin develop

After that, other team members can set up the project by pulling the latest changes:

git checkout develop
git pull origin develop

Finally, the team members should follow all the steps except the 1st one, as the project has already been generated.

By design, SOPS Age keys (secret keys) are Git-ignored and never committed to the repository. When using a local K3D cluster, secret keys are not shared and therefore should be recreated on another machine before proceeding with the steps:

rmk secret keys create
Example output ```text 2025-01-29T16:23:00.325+0100 INFO generate age key for scope: deps 2025-01-29T16:23:00.326+0100 INFO update SOPS config file: /home/user/rmk-test/etc/deps/develop/secrets/.sops.yaml 2025-01-29T16:23:00.337+0100 INFO generate age key for scope: rmk-test 2025-01-29T16:23:00.338+0100 INFO update SOPS config file: /home/user/rmk-test/etc/rmk-test/develop/secrets/.sops.yaml ```
If sharing the secret keys is required, consider **switching from a K3D provider** to a supported [cloud provider](configuration/configuration-management/configuration-management.md#initialization-of-rmk-configuration-for-different-cluster-providers).