AkôFlow Setup Guide: Kubernetes Local Setup (Docker Desktop)

This guide provides step-by-step instructions for setting up AkôFlow using Docker Desktop with Kubernetes. This is one of several deployment options for AkôFlow, specifically tailored for developers and users who prefer using Docker Desktop’s built-in Kubernetes for local development and testing.

Note: This guide focuses solely on the Docker Desktop with Kubernetes setup option. AkôFlow supports multiple runtime environments, including SDumont Supercomputer, Singularity, and other Kubernetes distributions. For those alternative deployment options, please refer to the appropriate documentation.

Requirements

  1. Docker Desktop:
    • Download and install Docker Desktop from Docker’s official website.
    • Ensure Kubernetes is enabled in Docker Desktop (instructions provided below).
  2. kubectl CLI:
    • Install kubectl to interact with the Kubernetes cluster.
    • Installation guide: Kubernetes CLI installation.
  3. AkôFlow Release Client:
  4. System Resources:
    • Minimum 4 CPUs and 4GB RAM allocated to Docker Desktop for Kubernetes.
    • Storage requirements depend on the workflows you plan to execute.

Step 1: Enable Docker Desktop and Kubernetes

  1. Install Docker Desktop:
    • Download and install Docker Desktop from the official website.
    • Launch Docker Desktop and sign in with your Docker Hub account if prompted.
  2. Enable Kubernetes:
    • Open Docker Desktop settings.
    • Navigate to Settings > Kubernetes.
    • Check Enable Kubernetes and click Apply & Restart.
  3. Verify Kubernetes is Running:
    • Open a terminal and check the status of Kubernetes: kubectl get nodes
    • Ensure the node status is Ready.

Step 2: Deploy AkôFlow Resources

  1. Apply the Resource File:
    • Deploy the AkôFlow service to the Docker Desktop Kubernetes cluster: kubectl apply -f https://raw.githubusercontent.com/UFFeScience/akoflow/refs/heads/main/pkg/server/resource/akoflow-dev-dockerdesktop-with-server.yaml
  2. Verify Deployment:
    • Check the status of the pods: kubectl get pods
    • Ensure all pods are in the Running state.
  3. Expose the AkôFlow Service:
    • The AkôFlow web interface will be available on port 8080. Use the following command to verify: kubectl get services
    • Confirm that the service is mapped to port 8080.

Step 3: Configure and Use the AkôFlow Client

  1. Download the AkôFlow Client:
    • Go to the AkôFlow Releases page and download the appropriate version for your system.
  2. Run the AkôFlow Client:
    • Use the AkôFlow client to interact with the AkôFlow server: akfclient --host localhost --port 8080 --file <workflow-file.yaml>
    • Replace <workflow-file.yaml> with the path to your workflow specification file.

Step 4: Access the AkôFlow Web Interface

  1. Access via Browser:
    • Open your web browser and navigate to: http://localhost:8080
  2. Monitor Workflows:
    • Use the web interface to view the status of running workflows, logs, and results.

Example Workflow Execution

  1. Prepare a Workflow Specification:
    • Create a YAML file for your workflow (e.g., example-workflow.yaml).
  2. Submit the Workflow:
    • Run the AkôFlow client to submit the workflow: akfclient --host localhost --port 8080 --file example-workflow.yaml
  3. Monitor Workflow Execution:
    • Use the web interface to monitor progress or check logs using kubectl: kubectl logs -f <workflow-pod-name>

Troubleshooting

  • Kubernetes Not Ready:
    • Ensure Docker Desktop has sufficient resources allocated under Settings > Resources.
  • Service Not Accessible:
    • Verify the service is exposed on port 8080 using: kubectl get services
  • Workflow Errors:
    • Check the logs of the workflow pod: kubectl logs <workflow-pod-name>

For more information about other deployment options and advanced configurations, please refer to the AkôFlow documentation.