Add a step-by-step documentation to expose a workload locally using k3d

[abbi-gaurav]

Description

Technically advanced users like to try out kyma locally. Using k3d is the easiest way to do it. However, there is no clear step-by-step documentation. It is scattered, and some steps may be wrong.

e.g. this local domain is no longer used

If you are using k3d, add httpbin.kyma.local to the entry with k3d IP in your system’s /etc/hosts file.

I tried myself and was able to put together a set of steps. Thanks to @triffer for resolving one misconfiguration issue:

Steps

• create k3d cluster

k3d cluster create kyma --kubeconfig-switch-context -p 30080:80@loadbalancer -p 30443:443@loadbalancer --k3s-arg "--disable=traefik@server:0"
kubectl create ns kyma-system

• Install Istio

kubectl label namespace kyma-system istio-injection=enabled --overwrite
kubectl apply -f https://github.com/kyma-project/istio/releases/latest/download/istio-manager.yaml
kubectl apply -f https://github.com/kyma-project/istio/releases/latest/download/istio-default-cr.yaml

• Deploy API gateway

kubectl label namespace kyma-system istio-injection=enabled --overwrite
kubectl apply -f https://github.com/kyma-project/api-gateway/releases/latest/download/api-gateway-manager.yaml
kubectl apply -f https://github.com/kyma-project/api-gateway/releases/latest/download/apigateway-default-cr.yaml

• update Core DNS to correctly resolve the local.kyma.dev domain

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: coredns-custom
  namespace: kube-system
data:
  kyma.override: |
    rewrite name regex (.*)\.local\.kyma\.dev istio-ingressgateway.istio-system.svc.cluster.local
EOF

kubectl rollout restart deployment -n kube-system coredns

• enable istio injection for default namespace

kubectl label namespace default istio-injection=enabled

• Deploy nginx

kubectl create deployment nginx --image=nginx --port=80
kubectl expose deployment nginx

• Create the API rule

cat <<EOF | kubectl apply -f -
apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: nginx
spec:
  gateway: kyma-system/kyma-gateway
  host: nginx
  rules:
  - accessStrategies:
    - handler: allow
    methods:
    - GET
    path: /.*
    service:
      name: nginx
      port: 80
status: {}
EOF

• A virtual service will get created

k get virtualservices.networking.istio.io
NAME          GATEWAYS                       HOSTS                      AGE
nginx-p5mhw   ["kyma-system/kyma-gateway"]   ["nginx.local.kyma.dev"]   24h

• Update /etc/hosts to point to nginx.local.kyma.dev

127.0.0.1 nginx.local.kyma.dev

• Access the service

curl https://nginx.local.kyma.dev:30443 -k -v

[Darshan-Movilitas]

This works fine. Thank you

[nataliasitko]

We have a similar flow already: Quick Install --> Create a Workload --> Expose a Workload that uses HTTPBin instead of nginx and should work on both k3d and Gardener. I’ll be working on the tutorials as part of this issue so they’re more straightforward also for developers who’d like to install API Gateway locally

The Quick Install guide should be the entry point for all Kyma tutorials that you can see on the kyma-project website, so I'd like to update the k3d cluster create... command there.

@abbi-gaurav @triffer I have a few questions regarding the steps:

• Is it possible to use the ports that managed Kyma uses by default instead of -p 30080:80@loadbalancer -p 30443:443@loadbalancer? It would be best if we could have the same version of API Gateway tutorials for managed and OS Kyma. If I understand correctly, with this change, I also need to add two versions of commands for accessing workloads, which I can do, but I'd rather keep it simple.
• If not, and we need to use ports 30080 and 30443, do you think there might be other tutorials for other modules that need updating (besides the ones for API Gateway)?
• Could you confirm that it is necessary to update Core DNS for the k3d installation? If so, I'll also add it to Quick Install for the API Gateway module

[mmitoraj]

@abbi-gaurav, could you have a look at the above comment, please?

[abbi-gaurav]

I think steps core DNS update are required. Regarding ports, it is not a must to use these ports. They can be some other ports. Since we are talking about running kyma locally, we need to use ports that are not reserved.

[strekm]

@nataliasitko @mmitoraj in quick install we have slightly different command:

`k3d cluster create --k3s-arg ‘--tls-san=host.docker.internal@server:*’
kubectl create ns kyma-system`

while in the issue:

k3d cluster create kyma --kubeconfig-switch-context -p 30080:80@loadbalancer -p 30443:443@loadbalancer --k3s-arg "--disable=traefik@server:0"
kubectl create ns kyma-system

this needs to be adjusted in quick install

[nataliasitko]

I've updated the command, added the step to update CoreDNS, and added a note about the ports. It's approved by Goats. @abbi-gaurav Could you also see if it's fine with you? Here's the PR: https://github.com/kyma-project/kyma/pull/18749/files