Skip to content

Latest commit

 

History

History
195 lines (138 loc) · 6.59 KB

quickstart.md

File metadata and controls

195 lines (138 loc) · 6.59 KB

Quickstart

Follow this guide if you want to see how the CN-WAN Operator automatically connects and manages a service registry on top of etcd.

Requirements

To run this, make sure you have:

  • A working etcd cluster: you can follow this guide to create a demo cluster for this quickstart
  • Access to a Kubernetes cluster running at least version 1.11.3 with support for LoadBalancer type of services and that can perform outbound HTTP/S requests successfully.
    • You can even try with KinD or Minikube, but make sure Load Balancers work.
  • Kubectl 1.11.3+

Finally, kubeconfig needs to be properly set up.

Let's go

1 - Clone the project

git clone https://github.com/CloudNativeSDWAN/cnwan-operator.git
cd ./cnwan-operator

2 - Deploy a test service

We will suppose you are deploying an application on your cluster where your employees can log in and watch training videos.

Run this to deploy a new namespace and a service in that namespace:

cat <<EOF | kubectl create -f -
kind: Namespace
apiVersion: v1
metadata:
    name: training-app-namespace
    labels:
        purpose: "test"
        operator.cnwan.io/watch: "enabled"
---
kind: Service
apiVersion: v1
metadata:
    name: web-training
    namespace: training-app-namespace
    labels:
        app: "training"
    annotations:
        version: "2.1"
        traffic-profile: "standard"
spec:
    ports:
        - name: port80
          protocol: TCP
          port: 80
          targetPort: 8080
    selector:
        app: "training"
    type: LoadBalancer
EOF

Please notice that the namespace has this label: operator.cnwan.io/watch: enabled which instructs the operator to watch events occurring in this namespace. Also notice that the service has annotations that will be registered as metadata:

annotations:
   traffic-profile: standard

Now verify that the namespace is there:

kubectl get ns

NAME                   STATUS   AGE
training-app-namespace          Active   1h

Verify that the service is there and has an IP:

kubectl get service -n training-app-namespace

NAME                   TYPE           CLUSTER-IP       EXTERNAL-IP    PORT(S)                       AGE
web-training           LoadBalancer   10.11.12.13      20.21.22.23    80:32058/TCP                  1h

If you see <none> or <pending> under EXTERNAL-IP you either have to wait to see an IP there or your cluster doesn't support LoadBalancer.

It doesn't really matter that there is no pod backing this service for now, as this is just a test. Of course, in a real world scenario you should make sure a pod is there.

3 - Provide settings

From the root directory navigate to artifacts/settings and modify the file settings.yaml to look like this - please provide appropriate values for host and port keys with your etcd cluster's addresses:

watchNamespacesByDefault: false
servicennotations:
  - traffic-profile
  - version
serviceRegistry:
  etcd:
    authentication: WithUsernameAndPassword
    endpoints:
    - host: <host-1>
      port: <port-1>
    - host: <host-2>
      port: <port-2>

If you have followed our demo cluster guide abd supposing the address you chose is 10.10.10.10, the your endpoints setting just looks like this:

endpoints:
- host: 10.10.10.10

Please notice the values inside serviceAnnotations:

  serviceAnnotations:
  - traffic-profile
  - version

This means that the operator will register traffic-profile as metadata if it finds it among a service's annotations list.

Important: if you don't have authentication mode you can remove authentication: WithUsernameAndPassword entirely. We encourage you to read and learn more about etcd settings.

4 - Deploy the operator

From the root directory of the project, execute one of the following lines:

# If you have username and password for etcd
./scripts/deploy.sh etcd --username <username> --password <password>

# If you don't have username and password for etcd
./scripts/deploy.sh etcd

5 - See it on etcd

Log in to etcd and look at data there with etcdctl - modify host:port and user accordingly:

etcdctl --endpoints http://host:port --user user:password get /service-registry/ --prefix

/service-registry is the prefix that all service registry objects will have on their key. This is the default value and it's there because we didn't configure CN-WAN operator with a different prefix.

Now, watch for changes there:

etcdctl --endpoints http://host:port --user user:password watch /service-registry/ --prefix

6 - Update metadata

Now you're basically done, but you can follow these additional steps to see more of the operator in action.

Suppose you made a mistake: this is a training application where your employees will follow video tutorials. Therefore, its kind of traffic - or, profile, must be video.

Execute:

kubectl annotate service web-training traffic-profile=video --overwrite -n training-app-namespace

The operator has updated the metadata in etcd accordingly.

7 - Add new metadata

Suppose you have a CI/CD pipeline that for each PR builds a container with a new tag. Also, it updates the service that serves the pods running that container by specifying the new version. Today, you will be that pipeline:

kubectl annotate service web-training version=2.2 -n training-app-namespace --overwrite

Once again, you will see that the metadata for that service have changed accordingly in etcd.

Where to go from here

Well, that's it for a quickstart. Now we encourage you to learn more about CN-WAN Operator by taking a look at the CN-WAN Operator docs and etcd docs.

Also, make sure you read the official documentation of CN-WAN to learn how you can apply this simple quickstart to a real world scenario.

Clean up

From the root directory of the project, run

./scripts/remove.sh
kubectl delete ns training-app-namespace