Skip to main content

Installation

We will walk you through the steps to set up a functioning local setup using KIND (Kubernetes IN Docker). OpenMFP leverages Flux, a tool designed to keep Kubernetes clusters synchronized with configuration sources, alongside Kustomize, a standalone tool for customizing Kubernetes resources. Together, these tools enable efficient and automated cluster management.

We will configure Flux to install, test and upgrade a demo app using OCIRepository and HelmRelease custom resources. Flux will monitor the Helm repository, and it will automatically upgrade the Helm releases to their latest chart version based on semver ranges.

By the end, you'll have a working setup ready to explore the full potential of OpenMFP while managing your cluster efficiently.

Prerequisites​

  1. Container Runtime
    Install either Docker or Podman to run the kind cluster:

    • Docker: Version 27.0.0 or higher. Installation Guide Get Docker
    • Podman: Version 5.1.0 or higher. Installation Guide Install Podman
      Ensure Docker or Podman is configured to use at least 12GB of memory.

    For Podman you will need to run:

    podman machine stop
    podman machine init --rootful --memory=12240
    podman machine start

    For Docker you will need to go to Docker Desktop -> Settings -> Resources -> Advanced and set the memory to 12GB.

  2. Kind (Kubernetes IN Docker)
    To set up a local Kubernetes cluster, use Kind. Follow the Kind Quick Start guide for more details. For macOS Installation via Homebrew run:

    brew install kind

  3. Helm
    Helm is required to bootstrap Flux. You can find detailed installation instructions here. For macOS Installation via Homebrew run:

    brew install helm

  4. Kubectl
    Kubectl is the Kubernetes command-line tool. You can install it using the following command:

    brew install kubectl

    For more installation options, refer to the Kubectl Installation Guide.

  5. GitHub setup
    Set GH_USER or install the GitHub CLI to setup your environment for Flux:

    • Specify your GitHub username by setting the GH_USER environment variable: 
      export GH_USER=<your-github-username>
    • Alternatively, install the GitHub CLI For macOS Installation via Homebrew run: 
      brew install gh

    Set a GitHub token to enable pulling OpenMFP Docker images, this token should have the read:packages scope.

    export GH_TOKEN=<your-github-token>

  6. Keycloak (Authentication Setup - Optional)
    You only need this step if you plan to use your own Keycloak instance. If not, a default Keycloak will be installed automatically during the setup process. To use your own Keycloak, set up the client secret as an environment variable:

    export KEYCLOAK_SECRET=<keycloak-client-secret>

  7. Free Port 8000
    The local OpenMFP portal will use port 8000. Ensure this port is not in use by another application before proceeding.

    • On Linux/macOS, you can check and free the port with the following commands:
    lsof -i :8000
    kill -9 <PID> # Replace <PID> with the process ID using the port

Bootstrap local environment​

Once the prerequisites are in place, follow these steps to set up the local environment:

  1. Clone the OpenMFP Repository
    Start by cloning the OpenMFP Helm charts repository:

    git clone https://github.com/openmfp/helm-charts
    cd helm-charts

  2. Run the Bootstrap Script
    The repository includes a script local-setup/scripts/start.sh, it contains all steps needed to bootstrap the local environment. The script will take some time and it automate the following steps:

    • Create kind cluster called openmfp
    • Install flux
    • Prepare secrets
    • Apply flux deployment configuration

    To start the bootstrapping and local installation, run the following command:

    ./local-setup/scripts/start.sh

  3. Access the Local Environment
    Once the bootstrap process finishes, you can access the local Demo OpenMFP Portal at: http://localhost:8000

Remove the Cluster​

If you want to delete the local environment and remove the KIND cluster, run the following command:

kind delete cluster --name openmfp

If the deletion is stuck validate that the container runtime (Docker or Podman) is started and running.

Troubleshooting​

If the bootstrap script does not successfully finish, connect to the kind-openmfp cluster, take the following steps to investigate:

  1. Verify the cluster is running and accessible:
kubectl cluster-info --context kind-openmfp
  1. Identify any pods that are not in the Running status:
kubectl get pods --all-namespaces | grep -v Running
  1. For pods that are stuck or failing, inspect the events for more details:
kubectl describe pod <pod-name> -n <namespace>

Review the Events section in the output to pinpoint and address the underlying issue.

  1. If the issue is related to memory constraints, increase the memory allocation for Docker or Podman as described in the Prerequisites section.