diff --git a/install/COMPATIBILITY-MATRIX.md b/install/COMPATIBILITY-MATRIX.md index 849b459..8de6739 100644 --- a/install/COMPATIBILITY-MATRIX.md +++ b/install/COMPATIBILITY-MATRIX.md @@ -29,14 +29,15 @@ If you're using Microcks in production, please contribute your configuration det The table below shows which Cloud Providers have been tested and validated with different Microcks versions: -| Certified Cloud Providers | 1.10.x | 1.11.x | 1.12.x | -|---------------------------|--------|--------|--------| -| Amazon Web Services | | | | -| Google Cloud Platform | | | | -| Microsoft Azure | | | | -| Oracle Cloud | | | | -| Scaleway | | | | -| OVH | | | | +| Certified Cloud Providers | 1.10.x | 1.11.x | 1.12.x | 1.14.x | +|---------------------------|--------|--------|--------|--------| +| Amazon Web Services | | | | | +| Google Cloud Platform | | | | | +| Microsoft Azure | | | | | +| Oracle Cloud | | | | | +| Scaleway | | | | | +| OVHcloud | | | | X | +|---------------------------|--------|--------|--------|--------| ### Kubernetes distrib diff --git a/install/GUIDELINES.md b/install/GUIDELINES.md index 5c711da..ba2693b 100644 --- a/install/GUIDELINES.md +++ b/install/GUIDELINES.md @@ -1,7 +1,7 @@ # Community-Driven Guidelines for Deploying Microcks in Cloud Production Environments ## Overview -This document provides a common guideline for deploying Microcks in production-grade cloud environments using managed Kubernetes services and leveraging cloud-native backing services. It serves as a framework adaptable to various cloud providers (**AWS**, **GCP**, **Azure**, **OVH**, **Oracle**, **Scaleway**, or **Koyeb**, etc.). +This document provides a common guideline for deploying Microcks in production-grade cloud environments using managed Kubernetes services and leveraging cloud-native backing services. It serves as a framework adaptable to various cloud providers (**AWS**, **GCP**, **Azure**, **OVHcloud**, **Oracle**, **Scaleway**, or **Koyeb**, etc.). The goal is to guide users through the deployment process by emphasizing the use of external Keycloak for authentication, native PostgreSQL-compatible databases for data management, and the deployment of Microcks via Helm charts. While the specific cloud provider implementations may vary (e.g., cloud provider-managed services like databases), the document focuses on the essential steps required, leaving the precise configuration and commands to be adapted based on the user’s cloud provider’s tools, documentation, and community-contributed examples. diff --git a/install/README.md b/install/README.md index 5587c03..db554be 100644 --- a/install/README.md +++ b/install/README.md @@ -13,8 +13,9 @@ Microcks is compatible with **managed Kubernetes services** such as: - **Amazon Elastic Kubernetes Service (EKS)** - **Google Kubernetes Engine (GKE)** -- **Microsoft Azure Kubernetes Service (AKS)** -- **Other platforms**: OVH, Oracle Cloud, Scaleway, etc. +- **Microsoft Azure Kubernetes Service (AKS)** +- **OVHcloud Managed Kubernetes Service (MKS)** +- **Other platforms**: Oracle Cloud, Scaleway, etc. This guide is part of a **collaborative community effort** to document deployment strategies for different cloud providers. If your preferred platform is not listed or lacks detailed instructions, feel free to **contribute** or **open an issue** in the [Microcks Community Repository](https://github.com/microcks/community). @@ -32,5 +33,5 @@ Below is a list of supported platforms, along with links to their official docum | **Google Cloud Platform** | Google Kubernetes Engine (GKE) | [GKE Documentation](https://cloud.google.com/kubernetes-engine/docs/quickstart) | [Completed – Awaiting Review and Feedback](https://github.com/microcks/community/tree/main/install/gcp) | | **Microsoft Azure** | Azure Kubernetes Service (AKS) | [AKS Documentation](https://learn.microsoft.com/en-us/azure/aks/) | [Completed – Awaiting Review and Feedback](https://github.com/microcks/community/tree/main/install/azure) | | **Oracle Cloud** | Oracle Container Engine for Kubernetes (OKE) | [OKE Documentation](https://docs.oracle.com/en-us/iaas/Content/ContEng/Concepts/contengoverview.htm) | [Completed – Awaiting Review and Feedback](https://github.com/microcks/community/tree/main/install/oracle) | -| **OVH** | OVH Managed Kubernetes | [OVH Kubernetes Documentation](https://docs.ovh.com/gb/en/kubernetes/) | [Looking for Contributions](https://github.com/microcks/community/tree/main/install/ovh) | +| **OVHcloud** | OVH Managed Kubernetes Service (MKS) | [OVHcloud Kubernetes Documentation](https://docs.ovhcloud.com/en/guides/public-cloud/containers-orchestration/managed-kubernetes/overview) | [Completed – Awaiting Review and Feedback](https://github.com/microcks/community/tree/main/install/ovhcloud) | | **Scaleway** | Scaleway Kubernetes Kapsule | [Scaleway Kapsule Documentation](https://www.scaleway.com/en/docs/containers/kapsule/) | [Looking for Contributions](https://github.com/microcks/community/tree/main/install/scaleway) | diff --git a/install/ovh/README.md b/install/ovh/README.md deleted file mode 100644 index 8210fcc..0000000 --- a/install/ovh/README.md +++ /dev/null @@ -1 +0,0 @@ -# Deploy Microcks on OVH diff --git a/install/ovhcloud/README.md b/install/ovhcloud/README.md new file mode 100644 index 0000000..3fb30ff --- /dev/null +++ b/install/ovhcloud/README.md @@ -0,0 +1,423 @@ +# Deploy Microcks on OVHcloud + +## Overview + +This guide provides a step-by-step approach to deploy **Microcks** on an **OVHcloud Managed Kubernetes Service (MKS)** cluster. It includes setting up **Gateway API** with **OVHcloud Public Cloud Load Balancer**. + +## Prerequisites + +Ensure the following tools are installed on your local system: + +1. **OVHcloud CLI:** [Install Guide](https://github.com/ovh/ovhcloud-cli/#installation) +2. **kubectl (Kubernetes CLI):** [Install Guide](https://kubernetes.io/docs/tasks/tools/#kubectl) +3. **Helm:** [Install Guide](https://helm.sh/docs/intro/install/) +4. An active OVHcloud account +5. An OVHcloud Public Cloud project +6. An OVHcloud API credential with sufficient permissions +7. A Domain Name (optional) if you want to set up a custom DNS + +## 1. Authenticate and configure the OVHcloud Public Cloud project + +OVHcloud CLI requires authentication to be able to make API calls. Run the following commands to export the needed enviroment variables. Replace , , and with your information. + +```sh +export OVH_ENDPOINT="ovh-eu" +export OVH_APPLICATION_KEY="" +export OVH_APPLICATION_SECRET="" +export OVH_CONSUMER_KEY="" +export OVH_CLOUD_PROJECT_SERVICE="" +``` + +Alternatively, you can use the `ovhcloud login` command to authenticate interactively or [use a configuration file](https://github.com/ovh/ovhcloud-cli/blob/main/doc/authentication.md#configuration-file). + +## 2. Create and configure an OVHcloud MKS cluster + +### 2.1 Create an OVHcloud MKS cluster + +Configure the Kubernetes cluster information: + +Define your cluster configuration: + +```sh +export CLUSTER_NAME="microcks" +export REGION="GRA9" +export PLAN="free" +``` + +Create the Kubernetes cluster: + +```sh +CLUSTER_ID=$(ovhcloud cloud mks create --name $CLUSTER_NAME --region $REGION --plan $PLAN | grep -oE '[0-9a-f-]{36}') +``` + +Wait for 2-3 minutes for the cluster to be provisioned. + +Check the status of the Kubernetes cluster: + +```sh +ovhcloud cloud mks get $CLUSTER_ID +``` + +For production usage, consider using a `standard` plan instead of the `free` plan. + +### 2.2 Create the MKS node pool + +Microcks is composed of several Kubernetes workloads, including the Microcks application, Keycloak and its PostgreSQL instance, MongoDB and the Postman runtime. + +For a small installation, a node pool with three general-purpose nodes is a reasonable starting point. + +Define your node pool configuration: + +```sh +export NODEPOOL_NAME="microcks-np" +export NODE_FLAVOR="b3-8" +``` + +Create the node pool: + +```sh +NP_ID=$(ovhcloud cloud mks nodepool create $CLUSTER_ID --flavor-name $NODE_FLAVOR --name $NODEPOOL_NAME --desired-nodes 3 --min-nodes 2 --max-nodes 3 | grep -oE '[0-9a-f-]{36}') +``` + +Wait for 3-4 minutes for the node pool to be provisioned. + +Check the status of the node pool: + +```sh +ovhcloud cloud mks nodepool get $CLUSTER_ID $NP_ID +``` + +### 2.3 Generate the kubeconfig and configure kubectl + +Once the cluster and node pool are ready, generate the Kubernetes configuration: + +```sh +ovhcloud cloud mks kubeconfig generate $CLUSTER_ID > microcks.yaml +``` + +Configure the kubectl CLI with the generated kubeconfig: + +```sh +export KUBECONFIG=$(pwd)/microcks.yaml +``` + +Display the node pool and the nodes information: + +```sh +kubectl get np +kubectl get nodes +``` + +You should see several nodes in the `Ready` state. + +## 3. Deploy Envoy Gateway API Controller + +Envoy Gateway implements the Kubernetes Gateway API and creates an Envoy proxy infrastructure for each Gateway. + +### 3.1 Install Envoy Gateway + +Install Envoy Gateway using Helm: + +```sh +helm install envoy-gateway oci://docker.io/envoyproxy/gateway-helm -n envoy-gateway-system --create-namespace +``` + +Check the installation: + +```sh +kubectl get pods -n envoy-gateway-system +``` + +All the pods should be in the `Running` state. + +### 3.2 Deploy the Envoy Gateway Class + +A `GatewayClass` defines which controller will manage your Gateways. +Create a `GatewayClass` for Envoy Gateway: + +```sh +cat < # Update with your email address + privateKeySecretRef: + name: letsencrypt-prod-microcks + solvers: + - http01: + gatewayHTTPRoute: + parentRefs: + - name: microcks-gateway + namespace: microcks + group: gateway.networking.k8s.io + kind: Gateway +EOF +``` + +### 3.4 Create the Envoy Gateway + +Microcks will reference a Gateway named `microcks-gateway`. + +Create the namespace: + +```sh +kubectl create namespace microcks +``` + +Create the `Gateway`: + +```sh +cat <.com + protocol: HTTP + port: 80 + allowedRoutes: + namespaces: + from: Same + + - name: microcks-https + hostname: microcks..com + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - name: microcks-tls + allowedRoutes: + namespaces: + from: Same + + - name: microcks-grpc + hostname: microcks-grpc..com + protocol: TLS + port: 443 + tls: + mode: Passthrough + allowedRoutes: + namespaces: + from: Same + + - name: keycloak-http + hostname: keycloak..com + protocol: HTTP + port: 80 + allowedRoutes: + namespaces: + from: Same + + - name: keycloak-https + hostname: keycloak..com + protocol: HTTPS + port: 443 + tls: + mode: Terminate + certificateRefs: + - name: keycloak-tls + allowedRoutes: + namespaces: + from: Same +EOF +``` + +Check the envoy Gateway is created and programmed: + +```sh +kubectl get gateway -n microcks +--- OUTPUT --- +NAME CLASS ADDRESS PROGRAMMED AGE +microcks-gateway envoy xx.xx.xx.xx. True 3m49s +``` + +At this stage, the Gateway should be `Accepted=True` and `Programmed=True`, wait a few minutes for the Gateway to be programmed and the OVHcloud Public Cloud Load Balancer to be provisioned. + +### 3.5 Configure DNS + +Get the external address assigned to the Gateway: + +```sh +export GATEWAY_IP=$(kubectl get gateway microcks-gateway \ + -n microcks \ + -o jsonpath='{.status.addresses[0].value}') + +echo $GATEWAY_IP +--- OUTPUT --- +xx.xx.xx.xx +``` + +If you are using a custom domain, create the following DNS records: + +```sh +microcks..com A +microcks-grpc..com A +keycloak..com A +``` + +You can do it easily at OVHcloud in the Domain names management console if you have your domain registered with OVHcloud: + +![OVHcloud DNS Domain Name](ovhcloud_dns_domain_name.png) + +After the creation, wait a little bit for the DNS propagation to be completed. You can check it with the following command: + +```sh +dig keycloak..com +noall +answer +dig microcks..com +noall +answer +dig microcks-grpc..com +noall +answer +``` + +Or, if you don't have a custom domain, you can use a free domain by using `nip.io` for your domain names, such as: + +``` +keycloak..nip.io +microcks..nip.io +``` + +## 4. Install Microcks using Helm + +### 4.1 Add Microcks Helm Repository + +```sh +helm repo add microcks https://microcks.io/helm/ +helm repo update +``` + +### 4.2 Create the configuration file for Microcks + +Create the `microcks_values.yaml` file with the configuration below. Replace the YOUR-DOMAIN placeholder with your actual value. + +```sh +cat > microcks_values.yaml <.com + ingressSecretRef: microcks-tls + generateCert: false + + grpcEnableTLS: true + +keycloak: + url: keycloak..com + privateUrl: http://microcks-keycloak.microcks.svc.cluster.local:8080 + ingressSecretRef: keycloak-tls + generateCert: false + + gatewayRefName: microcks-gateway + gatewayRefNamespace: microcks + gatewayRefSectionName: keycloak-https +EOF +``` + +### 4.3 Deploy Microcks + +```sh +helm install microcks microcks/microcks -n microcks -f microcks_values.yaml --create-namespace +``` + +### 4.4 Verify Microcks Pod Status + +Check that the Microcks pods are running: + +```sh +kubectl get pods -n microcks +--- OUTPUT --- +NAME READY STATUS RESTARTS AGE +microcks-7f9f994fbc-jd7pb 1/1 Running 0 19m +microcks-keycloak-5cf68c6b65-xjr6n 1/1 Running 3 (3m1s ago) 19m +microcks-keycloak-postgresql-6665b755f-zjdrl 1/1 Running 0 19m +microcks-mongodb-7ddff9f544-8rdcx 1/1 Running 0 19m +microcks-postman-runtime-5699859b86-58mr7 1/1 Running 0 19m +``` + +Wait until all pods are in the `Running` state and containers are ready. + + +### 4.5 Check HTTPRoutes + +```sh +kubectl get httproute -n microcks +--- OUTPUT --- +NAME HOSTNAMES AGE +microcks ["microcks..com"] 3m34s +microcks-keycloak ["keycloak..com"] 3m34s +``` + +Microcks is now available at: https://microcks..com. +gRPC mock service is available at: https://microcks-grpc.YOUR-DOMAIN.com. +Keycloak is available at: https://keycloak..com. + +🎉 Congratulations! You have successfully deployed Microcks on OVHcloud MKS. Now, you can start using Microcks to mock and test your APIs seamlessly in your cloud environment. + +## Cleanup (If Needed) + +To clean up resources: + +1. Delete the MKS cluster: + +```sh +ovhcloud cloud mks delete $CLUSTER_ID +``` +It will delete the cluster and all associated resources, including node pools, load balancers, and ingress controllers. + +2. Delete the DNS records you created for your domain. + +## Improvements + +This guide can be improved by implementing the following enhancements: +* Deploy the PostgreSQL DB on an **OVHcloud Managed Database** service instead of using the default PostgreSQL deployment in the Microcks Helm chart. +* Deploy the MongoDB on an **OVHcloud Managed Database** service instead of using the default MongoDB deployment in the Microcks Helm chart. + +This will provide better performance, scalability, and reliability for your Microcks installation. diff --git a/install/ovh/TROUBLESHOOTING.md b/install/ovhcloud/TROUBLESHOOTING.md similarity index 100% rename from install/ovh/TROUBLESHOOTING.md rename to install/ovhcloud/TROUBLESHOOTING.md diff --git a/install/ovhcloud/ovhcloud_dns_domain_name.png b/install/ovhcloud/ovhcloud_dns_domain_name.png new file mode 100644 index 0000000..51fef78 Binary files /dev/null and b/install/ovhcloud/ovhcloud_dns_domain_name.png differ