Getting Started with Apollo
To help you get started with Apollo, here is a simple tutorial to follow.
To complete this tutorial you will need:
- A working Kubernetes Cluster
-
kubectlwith context set to your Kubernetes cluster -
curlandjqinstalled
To run an Apollo application, we will use docker-compose to keep it simple:
git clone https://github.com/logzio/apollo.git
cd apollo/examples
docker-compose up -dApollo should run at http://localhost:30001/
Currently, defining Apollo Users and Permissions is supported only via API on port 8081.
Upon startup, Apollo ships with a default apollo@admin User and an admin Password. We will use these credentials to log in(feel free to delete it when you're done).
First, let's log in and save the session token:
# login as default admin user
token=`curl -s -X POST http://localhost:8081/_login \
-H 'content-type: application/json' \
-d '{
"username": "apollo@admin",
"password": "admin"
}' | jq .token | xargs`Now, let's create our first User and make it admin:
# setup new user
curl -X POST http://localhost:8081/signup?_token=$token \
-H 'content-type: application/json' \
-d '{
"firstName": "example_firstname",
"lastName": "example_lastname",
"userEmail": "[email protected]",
"password": "example_secret"
}'
# make it admin
curl -X PUT http://localhost:8081/users?_token=$token \
-H 'content-type: application/json' \
-d '{
"firstName": "example_firstname",
"lastName": "example_lastname",
"userEmail": "[email protected]",
"password": "example_secret",
"isEnabled": true,
"isAdmin": true
}'Let's log in again with our example User:
token=`curl -s -X POST http://localhost:8081/_login \
-H 'content-type: application/json' \
-d '{
"username": "[email protected]",
"password": "example_secret"
}' | jq .token | xargs`We will assume you have a working Kubernetes cluster with kubectl configured.
First, we must create an Apollo Kubernetes Service Account: (we will use the default namespace throughout this example)
kubectl create serviceaccount apollo
SECRET=`kubectl describe sa apollo | grep "Tokens:" | awk '{print $2}'`
SECRET_TOKEN=`kubectl describe secret $SECRET | grep "token:" | awk '{print $2}'`Now, Let's define the target Kubernetes Cluster and Namespace as an Apollo Environment:
# setup new environment
curl -X POST http://localhost:8081/environment?_token=$token \
-H 'content-type: application/json' \
-d '{
"name": "test",
"geoRegion": "us-east-1",
"availability": "staging",
"kubernetesMaster": "http://example.k8s.cluster.com:8080",
"kubernetesNamespace": "default",
"kubernetesToken": "$SECRET_TOKEN",
"servicePortCoefficient": 0,
"isActive": 1
}'Now, let's configure our first Apollo Service. We will define an nginx service that listens on node port 30100.
We can either use the API or web UI for that. Let's use the UI - now it's the time to log into Apollo with the user you just created!
Hit the Configure Service tab and apply the following Service and Deployment manifests as an Apollo Service named sample-apollo-app:
ngnix-service.yaml
apiVersion: v1
kind: Service
metadata:
labels:
role: sample-apollo-app
name: sample-apollo-app-service
spec:
ports:
- nodePort: 30100
port: 80
protocol: TCP
targetPort: 80
selector:
role: sample-apollo-app
type: NodePortngnix-deployment.yaml
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
labels:
role: sample-apollo-app
name: sample-apollo-app
spec:
replicas: 1
template:
metadata:
labels:
role: sample-apollo-app
spec:
containers:
- image: logzio/sample-apollo-app
imagePullPolicy: Always
name: sample-apollo-app
ports:
- containerPort: 80
protocol: TCP
restartPolicy: Always
As mentioned, we can also utilize the API to define Services and Deployments:
# setup new service and deployment
curl -X POST http://localhost:8081/service?_token=$token \
-H 'content-type: application/json' \
-d '{
"name": "sample-apollo-app",
"deploymentYaml": "...",
"serviceYaml": "...",
"isPartOfGroup": "false"
}'Apollo manages permissions by defining Roles that Users are assign to, and Deployment Permissions that Roles can deploy on.
Let's create a Role and assign our example User to it:
# setup deployment role
curl -X POST http://localhost:8081/deployment-roles?_token=$token \
-H 'content-type: application/json' \
-d '{
"name": "devs"
}'
# add user to deployment role
curl -X POST http://localhost:8081/deployment-roles/add-user?_token=$token \
-H 'content-type: application/json' \
-d '{
"userEmail": "[email protected]",
"deploymentRoleId": "1"
}'Now, let's create a Deployment Permission.
Permissions can be used to ALLOW or DENY deployment of Service on to an Environment.
We will add a Permission to allow deployment of the ngnix service we just created on the Kubernetes cluster we defined:
# setup deployment permission
curl -X POST http://localhost:8081/deployment-permission?_token=$token \
-H 'content-type: application/json' \
-d '{
"name": "Nginx allow",
"serviceId": "1",
"environmentId": "1",
"permissionType": "ALLOW"
}'Lastly, let's hook the Deployment Role with the Permission we just created:
# add permission to deployment role
curl -X POST http://localhost:8081/deployment-roles/add-deployment-permission?_token=$token \
-H 'content-type: application/json' \
-d '{
"deploymentRoleId": 1,
"deploymentPermissionId": 1
}'Now, to deploy our service, we will need to notify Apollo with the new Deployable Version. A Deployable Version is a git commit SHA of our Service GitHub repository. We will notify Apollo with a new Deployable Version:
curl -X POST http://localhost:8081/deployable-version?_token=$token \
-H 'content-type: application/json' \
-d '{
"gitCommitSha": "df821c0ce4dbacef9c5c79ccf0d4b1a59d150568",
"githubRepositoryUrl": "https://github.com/logzio/sample-apollo-app",
"serviceId": "1"
}'You should be able to successfully deploy your service.
Using the web UI, in the New Deployment tab, select the Environment and Service Version you want to deploy. You should see your service getting scheduled.
