Develop on KinD#

This guide walks you through the process to set up the Edge Orchestrator development environment on KinD and deploy ENIC (Edge Node in a Container) to run basic sanity tests. KinD and ENIC is useful to validate lifecycle management operations on already provisioned Edge Node.

Note

ENIC only emulates the real Edge Node and does not cover full Edge Node lifecycle management (from Day0 provisioning). To set up developer environment that is closest to the real-world deployment, see Develop on on-prem VM.

System Requirements#

Your development machine must meet the following minimum requirements:

Recommended Operating System: Ubuntu* 22.04 Server
Processor: 16 cores or more
Memory: 32 GB RAM or more
Disk Space: 256 GB SSD or more

Software Requirements#

Your development machine must have the following software installed:

asdf v0.16.5 or higher:
- Download the appropriate asdf binary for your operating system/architecture combo from the GitHub releases page. Ensure to place it in a directory on your $PATH. For example, you can prepend $ASDF_DATA_DIR/shims to your $PATH environment variable:
export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"
Docker* software

Development Environment Setup#

To set up your development environment, follow these steps:

Ensure your development machine meets the system and software requirements.

Clone the repository:

git clone https://github.com/open-edge-platform/edge-manageability-framework edge-manageability-framework
cd edge-manageability-framework

Install APT dependencies:

sudo apt-get update -y
sudo apt-get install -y \
    python3.10-venv \
    unzip

Install asdf plugins based on the versions specified in .tool-versions:

for plugin in golang jq mage; do
    asdf plugin add "${plugin}"
    asdf install "${plugin}"
done

mage asdfPlugins

Configure environment variables. ORCH_DEFAULT_PASSWORD will be your default password for different Edge Orchestator services. GIT_USER and GIT_TOKEN are required to download Git repositories, while DOCKERHUB_USERNAME and DOCKERHUB_TOKEN (DockerHub password) are required to avoid image pull rate-limiting issues.

Note

You can save these environment variables in your .bashrc.
```
export ORCH_DEFAULT_PASSWORD="ChangeMeOn1stLogin!"
export GIT_USER="git"
export GIT_TOKEN="" # provide your Git Personal Access Token
export DOCKERHUB_USERNAME="" # provide your DockerHub username
export DOCKERHUB_TOKEN="" # provide your DockerHub password
```
Decide on the orchestrator profile you want to deploy.
- Use dev profile (defined in orch-configs/clusters/dev.yaml) to deploy full Edge Orchestrator (including Observability, SRE, Kyverno, etc.).
- Use dev-minimal profile (defined in orch-configs/clusters/dev-minimal.yaml) to deploy a minimal version of Edge Orchestrator. It’s recommended profile unless you need the above-mentioned extensions.
- [OPTIONAL] Customize the orchestrator profile. For example, if you only need to develop Edge Infrastructure Manager, you can disable application and cluster orchestration by removing the following lines from the profile YAML definition:
```
- orch-configs/profiles/enable-app-orch.yaml
- orch-configs/profiles/enable-cluster-orch.yaml
```
If you require a proxy for internet access, you can modify httpProxy, httpsProxy, and noProxy parameters in the orch-configs/profiles/proxy-none.yaml file.
Deploy the Edge Orchestrator on KinD:
- Use mage deploy:kindAll if you use dev profile.
- Use mage deploy:kindMinimal if you use dev-minimal profile.
The deployment will start. To check the status of the deployment, you can run:
```
mage deploy:waitUntilComplete
```
This command will block until the deployment is complete.

You can also observe the deployment status by viewing the ArgoCD dashboard. Use admin/ChangeMeOn1stLogin! credentials.

# Access to ArgoCD UI from outside
kubectl port-forward -n argocd service/argocd-server 8080:443 --address 0.0.0.0
# Use <MACHINE-IP>:8080 to access ArgoCD.

Once completed, add Edge Orchestrator server TLS certificate to the system’s trusted store:
```
mage gen:orchCA deploy:orchCA
```
Restart Traefik proxy to make Edge Orchestrator endpoints reachable from the outside.
```
mage router:stop router:start
```
Generate static DNS entries and put the output in the /etc/hosts. You need to insert these entries to /etc/hosts on every machine, from which you access the Edge Orchestrator.
```
mage gen:hostfileTraefik
```

If needed, create default tenants and users:

mage tenantUtils:createDefaultMtSetup
mage devUtils:createDefaultUser

You have successfully set up your KinD-based development environment for Edge Orchestrator.

You can now start developing and testing your changes.

You can now reach the Edge Orchestrator UI at https://web-ui.kind.internal.
To deploy, register and provision ENiC:
- To deploy ENiC run the command below. The first argument defines number of ENiCs you want to deploy. For the second argument choose dev or dev-minimal, based on the orchestrator profile you selected.
```
ORCH_ORG=sample-org
ORCH_PROJECT=sample-project
ORCH_USER=sample-project-onboarding-user
ORCH_USER_API=sample-project-api-user
mage devUtils:deployEnic 1 dev
```
- ENiC Pod(s) wil be created and running. You can list ENiC Pods with:
```
kubectl get pods -n enic
```
- To grab ENiC logs use commands from the ENiC documentation.
- At this point ENiC Pod(s) will only be deployed, but won’t be registered/onboarded to the Edge Orchestrator or provisioned. To get emulated hardware details (UUID, Serial Number - may be needed for further registration) run:
```
mage devUtils:getEnicSerialNumber
mage devUtils:getEnicUUID
```
- If needed, perform automated registration and provisioning. By default, ENiC will provisioned with Ubuntu OS. Note that you will need to repeat these command for all ENiC Pods if you deploy more than one.
```
ORCH_USER=sample-project-api-user mage devUtils:registerEnic enic-0

ORCH_USER=sample-project-api-user mage devUtils:provisionEnic enic-0
```
- Wait until ENiC is provisioned:
```
mage devUtils:WaitForEnic
```

To get the default admin password, run:

kubectl get secret platform-keycloak -n orch-platform -o jsonpath='{.data.admin-password}' | base64 --decode

To get the default admin password for Argo CD tool, run:

kubectl get secret argocd-initial-admin-secret -n argocd -o jsonpath="{.data.password}" | base64 -decode

To tear down the deployment run:
```
mage undeploy:kind clean
```

Make changes#

See Obtaining Code and Contributing Changes to learn more about how to make changes to an Edge Orchestrator component.

Code Standards#

The project follows specific coding standards to ensure consistency and readability. Please adhere to the following guidelines when contributing:

Golang#

Follow the guidelines in Effective Go.
Use gofmt to format your code.
Write clear and concise comments for exported functions, types, and packages.
Use idiomatic Go constructs and avoid unnecessary complexity.
Ensure that your code is well-tested and includes unit tests for all functions.
Use descriptive variable and function names that clearly convey their purpose.
Avoid global variables and prefer dependency injection where possible.
Handle errors gracefully and provide meaningful error messages.
Code must pass mage lint:golang to ensure proper formatting.

Helm*#

Follow the Helm Best Practices.
Use meaningful names for charts, templates, and values.
Code must pass mage lint:helm to ensure proper formatting.

Markdown#

Use proper Markdown syntax for headings, lists, links, and code blocks.
Code must pass mage lint:markdown to ensure proper formatting.

Shell Script#

Use #!/usr/bin/env bash at the top of your scripts to specify the shell.
Always use set -o errexit to ensure the script exits on the first error.
Use set -o nounset to treat unset variables as an error.
Use set -o pipefail to catch errors in pipelines.
Write clear and concise comments to explain the purpose of complex commands.
Use functions to encapsulate and reuse code.
Check the exit status of commands and handle errors appropriately.
Avoid using hardcoded paths; use variables and configuration files instead.
Ensure your scripts are idempotent and can be run multiple times without causing issues.
Use the long form of commands (e.g., –verbose instead of -v) for clarity.
Code must pass mage lint:shell to ensure proper formatting.

Terraform#

Follow the Terraform Style Guide.
Code must pass mage lint:terraform to ensure proper formatting.

YAML#

Use proper YAML syntax for indentation, lists, and key-value pairs.
Ensure that your YAML files are valid and well-structured.
Code must pass mage lint:yaml to ensure proper formatting.

Continuous Integration#

Submit a pull request (PR) to the main branch of the repository.
Wait for the CI to run and verify that all checks pass before merging.
If your PR is a work in progress, mark it as a draft to indicate that it’s not ready for review yet.
Ensure that your code passes all continuous integration (CI) checks.
Address any feedback or requested changes from the CI or code reviewers.
If your PR introduces new features or changes existing functionality, ensure that it includes appropriate tests. If it fixes a bug, include a test that demonstrates the bug and verifies the fix whenever possible. This helps prevent the bug from reoccurring in the future.
Use descriptive commit messages that clearly explain the changes made.
Break down large changes into smaller, manageable commits to make it easier for reviewers to understand.
Ensure that your code is well-documented and includes comments where necessary to explain complex logic or decisions.
Keep your PR focused on a single change or feature to make it easier for reviewers to provide feedback.
Respond to code reviews in a timely manner and be open to feedback.
If your PR is related to a specific issue, reference that issue in the PR description to provide context.
Pin all dependencies to a specific patch version at a minimum in your code to ensure reproducibility.
Code should be reusable and portable across platforms. Avoid writing code that is tightly coupled to a specific CI environment. All code that runs in CI should be able to run locally as well.
CI workflows should primarily be executing the same Mage commands that a developer would run locally. There should not be any “magic” in the CI that is not also available locally.

Testing#

Write unit, integration, and E2E tests for your code.
Ensure all static analysis and tests pass before submitting a pull request.
Aim for high test coverage to ensure code reliability.

Documentation#

Update the documentation to reflect your changes.
Write clear and concise docstrings for all functions, classes, and modules.