serverless-manager

README

Serverless Manager

Overview

Serverless Manager allows deploying the Serverless component on the Kyma cluster in compatibility with the Lifecycle Manager.

Prerequisites

• Access to a k8s cluster
• Go
• k3d
• Docker
• kubectl
• Kubebuilder

Installation on the k3d cluster

1. Clone the project.

   git clone https://github.com/kyma-project/serverless-manager.git && cd serverless-manager/
   

2. Build the manager locally and run it on the k3d cluster.

   make local-run
   

NOTE: To clean up the k3d cluster, use the make local-stop make target.

Manual installation on the k3d cluster

1. Clone the project.

   git clone https://github.com/kyma-project/serverless-manager.git && cd serverless-manager/
   

2. Provision the k3d cluster.

   kyma provision k3d
   

3. Install prerequisites.

   kyma deploy -s main --component cluster-essentials --profile production --ci
   

   NOTE: This step is required only because serverless-manager is in the early stage, and there is no manager for the Kyma CRDs installation.

4. Build and push the Serverless Manager image.

   make module-image IMG_REGISTRY=localhost:5001/unsigned/operator-images IMG=localhost:5001/serverless-manager-dev-local:0.0.1
   

5. Build and push the Serverless module.

   make module-build IMG=k3d-kyma-registry:5001/serverless-manager-dev-local:0.0.1 MODULE_REGISTRY=localhost:5001/unsigned
   

6. Verify if the module and the manager's image are pushed to the local registry.

   curl localhost:5001/v2/_catalog
   

   You should get a result similar to this example:

   {"repositories":["serverless-manager-dev-local","unsigned/component-descriptors/kyma.project.io/module/serverless"]}
   

7. Inspect the generated module template.

   NOTE: The following sub-steps are temporary workarounds.

   Edit template.yaml under the config/moduletemplates folder and:

   • change target to control-plane

   spec:
       target: control-plane
   

   NOTE: This is required in the single cluster mode only.

   • change the existing repository context in spec.descriptor.component:

   repositoryContexts:                                                                           
     - baseUrl: k3d-kyma-registry.localhost:5000/unsigned
       componentNameMapping: urlPath                                                               
       type: ociRegistry
   

   NOTE: Because Pods inside the k3d cluster use the docker-internal port of the registry, it tries to resolve the registry against port 5000 instead of 5001. K3d has registry aliases, but lifecycle-manager is not part of k3d and thus does not know how to properly alias k3d-kyma-registry.localhost:5001.

8. Install modular Kyma on the k3d cluster.

   This installs the latest versions of lifecycle-manager.

   Use the --template flag to deploy the Serverless module manifest from the beginning, or apply it using kubectl later.

   kyma alpha deploy --templates=./config/moduletemplates/template.yaml
   

   Kyma installation is ready, but the module is not yet activated.

   kubectl get kymas.operator.kyma-project.io -A
   

   You should get a result similar to the following example:

   NAMESPACE    NAME           STATE   AGE
   kyma-system   default-kyma   Ready   71s
   

   Serverless Module is a known module, but not activated.

   kubectl get moduletemplates.operator.kyma-project.io -A 
   

   You should get a result similar to the following example:

   NAMESPACE    NAME                  AGE
   kcp-system   moduletemplate-serverless   2m24s
   

9. Give Lifecycle Manager permission to install CustomResourceDefinition (CRD) cluster-wide.

   lifecycle-manager must be able to apply CRDs to install modules. In the remote mode (with control-plane managing remote clusters) it gets an administrative kubeconfig, targeting the remote cluster to do so. In the local mode (single-cluster mode), it uses Service Account and does not have permission to create CRDs by default.

   Run the following command to make sure the Lifecycle Manager's Service Account gets an administrative role:

   kubectl edit clusterrole lifecycle-manager-manager-role
   

   And add the following element under rules:

   - apiGroups:
     - "*"
     resources:
     - "*"                  
     verbs:                  
     - "*"
   

   NOTE: This is a temporary workaround and is only required in the single-cluster mode.

10. Enable Serverless in the Kyma custom resource (CR)

    kubectl edit kymas.operator.kyma-project.io -n kyma-system default-kyma
    

    And add the following field under spec:

      modules:
      - name: serverless
        channel: alpha
    

Manual installation

1. Clone the project.

   git clone https://github.com/kyma-project/serverless-manager.git && cd serverless-manager/
   

2. Set the serverless-manager image name.

   export IMG=<DOCKER_USERNAME>/custom-serverless-manager:0.0.1
   

3. Verify the compability.

   make test
   

4. Build and push the image to the registry.

   make module-image
   

5. Deploy.

   make deploy
   

Using serverless-manager

• Create a Serverless instance.

  kubectl apply -f config/samples/operator_v1alpha1_serverless_k3d.yaml
  

• Delete a Serverless instance.

  kubectl delete -f config/samples/operator_v1alpha1_serverless_k3d.yaml
  

• Use external registry.

  The following example shows how you can modify the Serverless docker registry address using the serverless.operator.kyma-project.io CR:

  kubectl create secret generic my-secret \
      --namespace kyma-system \
      --from-literal username="<USERNAME>" \
      --from-literal password="<PASSWORD>" \
      --from-literal serverAddress="<SERVER_ADDRESS>" \
      --from-literal registryAddress="<REGISTRY_ADDRESS>"
  

  NOTE: For DockerHub:

  • SERVER_ADDRESS is "https://index.docker.io/v1/",
  • USERNAME and REGISTRY_ADDRESS must be identical.

  cat <<EOF | kubectl apply -f -
  apiVersion: operator.kyma-project.io/v1alpha1
  kind: Serverless
  metadata:
  name: serverless-sample
  spec:
      dockerRegistry:
          enableInternal: false
          secretName: my-secret
  EOF
  

Troubleshooting

• For MacBook M1 users

  Some parts of the scripts may not work because the Kyma CLI is not released for Apple Silicon users. To fix it install Kyma CLI manually and export the path to it.

  export KYMA=$(which kyma)
  

  The example error may look like this: Error: unsupported platform OS_TYPE: Darwin, OS_ARCH: arm64; to mitigate this problem set variable KYMA with the absolute path to kyma-cli binary compatible with your operating system and architecture. Stop.