• Setup a Kubernetes Cluster

    Setup a Kubernetes Cluster

    This is work in progress. We will add its sections in pieces. Your feedback is welcome at discuss.istio.io.

    In this module, you set up a Kubernetes cluster that has Istio installed and anamespace to use throughout the tutorial.

    If you are in a workshop and the instructors provide a cluster for you,proceed to setting up your local computer.

    • Ensure you have access to a Kubernetes cluster.You can use the Google Kubernetes Engine or theIBM Cloud Kubernetes Service.

    • Connect to your cluster and create an environment variable to store the nameof a namespace that you will use when you run the tutorial commands.You can use any name, for example tutorial.

    1. $ export NAMESPACE=tutorial
    • Create the namespace:
    1. $ kubectl create namespace $NAMESPACE

    If you are an instructor, you should allocate a separate namespace per eachparticipant. The tutorial supports work in multiple namespacessimultaneously by multiple participants.

    • Install Istio with strict mutual TLS enabled. TODO: add command or point to instructions.

    • Enable Envoy’s access logging.

    • Create a Kubernetes Ingress resource for these common Istio services usingthe kubectl command shown. It is not necessary to be familiar with each ofthese services at this point in the tutorial.

      • Grafana
      • Jaeger
      • Prometheus
      • KialiThe kubectl command can accept an in-line configuration to create theIngress resources for each service:
    1. $ kubectl apply -f - <<EOF
    2. apiVersion: extensions/v1beta1
    3. kind: Ingress
    4. metadata:
    5.   name: istio-system
    6.   namespace: istio-system
    7. spec:
    8.   rules:
    9.   - host: my-istio-dashboard.io
    10.     http:
    11.       paths:
    12.       - path: /
    13.         backend:
    14.           serviceName: grafana
    15.           servicePort: 3000
    16.   - host: my-istio-tracing.io
    17.     http:
    18.       paths:
    19.       - path: /
    20.         backend:
    21.           serviceName: tracing
    22.           servicePort: 80
    23.   - host: my-istio-logs-database.io
    24.     http:
    25.       paths:
    26.       - path: /
    27.         backend:
    28.           serviceName: prometheus
    29.           servicePort: 9090
    30.   - host: my-kiali.io
    31.     http:
    32.       paths:
    33.       - path: /
    34.         backend:
    35.           serviceName: kiali
    36.           servicePort: 20001
    37. EOF
    • Create a role to provide read access to the istio-system namespace. Thisrole is required to limit permissions of the participants in the stepsbelow.
    1. $ kubectl apply -f - <<EOF
    2. kind: Role
    3. apiVersion: rbac.authorization.k8s.io/v1beta1
    4. metadata:
    5.   name: istio-system-access
    6.   namespace: istio-system
    7. rules:
    8. - apiGroups: ["", "extensions", "apps"]
    9.   resources: ["*"]
    10.   verbs: ["get", "list"]
    11. EOF
    • Create a service account for each participant:
    1. $ kubectl apply -f - <<EOF
    2. apiVersion: v1
    3. kind: ServiceAccount
    4. metadata:
    5.   name: ${NAMESPACE}-user
    6.   namespace: $NAMESPACE
    7. EOF
    • Limit each participant’s permissions. During the tutorial, participants onlyneed to create resources in their namespace and to read resources fromistio-system namespace. It is a good practice, even if using your owncluster, to avoid interfering with other namespaces inyour cluster.

    Create a role to allow read-write access to each participant’s namespace.Bind the participant’s service account to this role and to the role forreading resources from istio-system:

    1. $ kubectl apply -f - <<EOF
    2. kind: Role
    3. apiVersion: rbac.authorization.k8s.io/v1beta1
    4. metadata:
    5.   name: ${NAMESPACE}-access
    6.   namespace: $NAMESPACE
    7. rules:
    8. - apiGroups: ["", "extensions", "apps", "networking.k8s.io", "networking.istio.io", "authentication.istio.io",
    9.               "rbac.istio.io", "config.istio.io"]
    10.   resources: ["*"]
    11.   verbs: ["*"]
    12. ---
    13. kind: RoleBinding
    14. apiVersion: rbac.authorization.k8s.io/v1beta1
    15. metadata:
    16.   name: ${NAMESPACE}-access
    17.   namespace: $NAMESPACE
    18. subjects:
    19. - kind: ServiceAccount
    20.   name: ${NAMESPACE}-user
    21.   namespace: $NAMESPACE
    22. roleRef:
    23.   apiGroup: rbac.authorization.k8s.io
    24.   kind: Role
    25.   name: ${NAMESPACE}-access
    26. ---
    27. kind: RoleBinding
    28. apiVersion: rbac.authorization.k8s.io/v1beta1
    29. metadata:
    30.   name: ${NAMESPACE}-istio-system-access
    31.   namespace: istio-system
    32. subjects:
    33. - kind: ServiceAccount
    34.   name: ${NAMESPACE}-user
    35.   namespace: $NAMESPACE
    36. roleRef:
    37.   apiGroup: rbac.authorization.k8s.io
    38.   kind: Role
    39.   name: istio-system-access
    40. EOF
    • Each participant needs to use their own Kubernetes configuration file. This configuration file specifiesthe cluster details, the service account, the credentials and the namespace of the participant.The kubectl command uses the configuration file to operate on the cluster.

    Generate a Kubernetes configuration file for each participant:

    1. $ cat <<EOF > ./${NAMESPACE}-user-config.yaml
    2. apiVersion: v1
    3. kind: Config
    4. preferences: {}
    6. clusters:
    7. - cluster:
    8.     certificate-authority-data: $(kubectl get secret $(kubectl get sa ${NAMESPACE}-user -n $NAMESPACE -o jsonpath={.secrets..name}) -n $NAMESPACE -o jsonpath='{.data.ca\.crt}')
    9.     server: $(kubectl config view -o jsonpath="{.clusters[?(.name==\"$(kubectl config view -o jsonpath="{.contexts[?(.name==\"$(kubectl config current-context)\")].context.cluster}")\")].cluster.server}")
    10.   name: ${NAMESPACE}-cluster
    12. users:
    13. - name: ${NAMESPACE}-user
    14.   user:
    15.     as-user-extra: {}
    16.     client-key-data: $(kubectl get secret $(kubectl get sa ${NAMESPACE}-user -n $NAMESPACE -o jsonpath={.secrets..name}) -n $NAMESPACE -o jsonpath='{.data.ca\.crt}')
    17.     token: $(kubectl get secret $(kubectl get sa ${NAMESPACE}-user -n $NAMESPACE -o jsonpath={.secrets..name}) -n $NAMESPACE -o jsonpath={.data.token} | base64 --decode)
    19. contexts:
    20. - context:
    21.     cluster: ${NAMESPACE}-cluster
    22.     namespace: ${NAMESPACE}
    23.     user: ${NAMESPACE}-user
    24.   name: ${NAMESPACE}
    26. current-context: ${NAMESPACE}
    27. EOF
    • If you are setting up the cluster for yourself, copy the${NAMESPACE}-user-config.yaml file mentioned in the previous steps to yourlocal computer, where ${NAMESPACE} is the name of the namespace youprovided in the previous steps. For example, tutorial-user-config.yaml.You will need this file later in the tutorial.

    If you are an instructor, send the generated configuration files to eachparticipant who should copy it to their local computer.

    Congratulations, you configured your cluster for the tutorials!

    You are ready to setup a local computer.