In order to deploy Realm Object Server using Kubernetes, you must have a Kubernetes Cluster available to you. Fortunately, you can easily run Kubernetes on your workstation if you're looking for a quick start.
Our cluster deployment utilizes Kubernetes. Before you get started, you'll need to create a cluster if you do not already have one.
The easiest way to get started with Kubernetes is by using Docker for Mac. Start by downloading Docker for Mac here. Be sure to use the download link for "Get Docker CE for Mac (edge)." You will need to register or sign in to the Docker Store in order to download. Then, follow the provided install instructions.
If you have not already done so, launch the Docker application that you downloaded. Then, open the preferences and enable Kubernetes in the "Kubernetes" tab. Click "Apply" and wait a few minutes while Kubernetes starts.
After installation, verify that you have the latest version that was tested with this documenation:
$ docker versionClient:Version: 18.05.0-ceAPI version: 1.37Go version: go1.9.5Git commit: f150324Built: Wed May 9 22:12:05 2018OS/Arch: darwin/amd64Experimental: falseOrchestrator: swarmServer:Engine:Version: 18.05.0-ceAPI version: 1.37 (minimum version 1.12)Go version: go1.10.1Git commit: f150324Built: Wed May 9 22:20:16 2018OS/Arch: linux/amd64Experimental: true
Most major cloud cloud providers offer some kind of managed Kubernetes service. Microsoft Azure uses Azure Kubernetes Service (AKS)
Creating a cluster is easy with AKS. You can use their quickstart guide as a reference. After you create the cluster, we recommend ensuring that you can connect via the
kubectl CLI. This is also explained in the quickstart guide. At the time of writing, you can do this from an Azure cloud shell with the following command:
##input your cluster information for connectionaz aks get-credentials --resource-group myResourceGroup --name myAKSCluster##verify connection by getting cluster informationkubectl get nodes
Most major cloud cloud providers offer some kind of managed Kubernetes service. IBM Cloud uses IBM Cloud Kubernetes Service.
Creating a cluster is easy. You can use their cluster creation tutorial as a reference. After you create the cluster, we recommend ensuring that you can connect via the
kubectl CLI. Once you can connect to the cluster via
kubectl you can proceed with the rest of the instructions to install Helm tiller and then the Realm Object Server cluster. Here are some terminal commands that you might find useful when first getting started. You'll need to tailor these to your specific region and cluster information based on how you created your cluster.
##Login to your IBM Cloud accountibmcloud login -a https://api.ng.bluemix.net##Target the IBM Cloud Container Service region in which you want to work.ibmcloud cs region-set us-south##Get the command to set the environment variable and download the Kubernetes configuration files.#this assumes a cluster named "ros-kubernetes"ibmcloud cs cluster-config ros-kubernetes##Set the KUBECONFIG environment variable. Copy the output from the previous command and paste it in your terminal.#The command output should look similar to the following.#This will configure your CLI to connect to your cluster properlyexport KUBECONFIG=/Users/$USER/.bluemix/plugins/container-service/clusters/ros-kubernetes/kube-config-hou02-ros-kubernetes.yml##Verify connection by getting cluster informationkubectl get nodes
Our recommended Realm Object Server installation method requires Kubernetes' Helm command line utility.
If you use macOS, you can use Homebrew to install it. Otherwise, refer to Helm's documentation.
brew install kubernetes-helm
If you have a new cluster, or one that has not been prepared with Tiller, you can do so using the CLI tool that you installed:
helm init --upgrade --wait
Using Helm and Tiller in Azure is easy, and you will find the process documented here. We recommend using the Azure Cloud Shell which comes with the Helm CLI already installed. After this, you will need to configure Helm which is detailed in the article linked above.
Using Helm and Tiller is the easiest way to get the Realm Object Server deployed in your IBM Cloud Cluster. You'll want to follow their documentation on Helm to ensure the smoothest installation experience.
At a high level, the process will consist of the following:
Install the Helm CLI
Verify a succesful installation
If you're running a cluster using Docker for Mac, you can use Helm to easily install the Kubernetes Dashboard in your cluster:
helm install --kube-context=docker-for-desktop --wait \--name kubernetes-dashboard --namespace kube-system \--set service.type=NodePort,service.nodePort=30443 \stable/kubernetes-dashboard
Confirm that you can access the UI at the URL: https://127.0.0.1:30443/. Bypass the insecure certificate warning, and choose "Skip" when presented with an authentication dialog.
Realm maintains a Helm Chart that can be used to install and maintain your deployed Realm Object Server. Think of it as APT or RPM, but for distributed applications.
Our charts are hosted on Github, and can be added to Helm with the following command:
helm repo add realm https://realm.github.io/charts
You should have access to a Realm Object Server Feature Token. This token must be passed to our Helm chart in order for Realm Object Server to operate. You can do so with an overrides file that preempts the Helm chart's values file:
Once you have created an overrides file, you can use it when deploying:
helm install realm/realm-object-server -f overrides.yaml
When successful, you should see some output similar to:
NAME: foolish-octopusLAST DEPLOYED: Thu Jun 21 20:11:02 2018NAMESPACE: defaultSTATUS: DEPLOYEDRESOURCES:==> v1/RoleNAME AGEfoolish-octopus-sync-default 1s==> v1/StatefulSetNAME DESIRED CURRENT AGEfoolish-octopus-sync-default 1 1 1s==> v1/RoleBindingNAME AGEfoolish-octopus-sync-default 1s==> v1/ServiceNAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGEfoolish-octopus-realm-object-server NodePort 10.103.219.36 <none> 80:30080/TCP 1sfoolish-octopus-metrics ClusterIP 10.110.66.250 <none> 9081/TCP 1sfoolish-octopus-sync-default ClusterIP 10.105.177.213 <none> 7800/TCP,9080/TCP 1s==> v1/SecretNAME TYPE DATA AGEfoolish-octopus Opaque 1 1s==> v1/ConfigMapNAME DATA AGEfoolish-octopus 3 1s==> v1/ServiceAccountNAME SECRETS AGEfoolish-octopus-sync-default 1 1s==> v1/DeploymentNAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGEfoolish-octopus-realm-object-server 1 1 1 0 1s==> v1/EndpointsNAME ENDPOINTS AGEfoolish-octopus-sync-default <none> 1s==> v1/Pod(related)NAME READY STATUS RESTARTS AGEfoolish-octopus-realm-object-server-547948d998-zgwbq 0/1 ContainerCreating 0 1sfoolish-octopus-sync-default-0 0/1 ContainerCreating 0 1s
As you can see, Helm named our deployment
foolish-octopus. You can set your own name for the deployment at installation by using the chart
--name parameter. But to avoid confusion, we're treating it like a constant throughout.
$ helm listNAME REVISION UPDATED STATUS CHART NAMESPACEkubernetes-dashboard 1 Thu Jun 7 16:00:46 2018 DEPLOYED kubernetes-dashboard-0.7.0 kube-systemfoolish-octopus 3 Thu Jun 21 20:11:02 2018 DEPLOYED realm-object-server-0.1.0 default
For future reference, you can uninstall Realm Object Server using the following command. If you get stuck, this might be the best course of action, after which you can start over:
helm delete --purge foolish-octopus
In order to obtain logs from Realm Object Server, we must first identify their pods:
$ kubectl get podsNAME READY STATUS RESTARTS AGEfoolish-octopus-realm-object-server-5f4fcbfbfc-gp7l2 1/1 Running 0 1hfoolish-octopus-sync-default-0 1/1 Running 2 1h
The first pod listed is Realm Object Server without the sync server. That identifies it as "core services". The second pod listed is the sync worker. Use the pod names to obtain logs:
kubectl logs foolish-octopus-realm-object-server-5f4fcbfbfc-gp7l2kubectl logs foolish-octopus-sync-default-0
We already demonstrated how to override the chart's default configuration when we provided the feature token. If, for example, you would like to expose Realm Object Server by NodePort (suitable when using Docker for Mac), you can simply add to the overrides file
Now that we've verified that Realm Object Server is running, we can override the chart defaults in order to expose it. Open
overrides.yaml using your favorite editor and add a service:
sync:featureToken: YOUR_FEATURE_TOKEN_HEREservice:type: NodePortnodePort: 30080
This file is the same structure and format of the chart's
values.yaml. You can refer to that file for all configurable attributes: https://github.com/realm/charts/blob/master/realm-object-server/values.yaml
Now we can update our release with these modifications:
helm upgrade foolish-octopus realm/realm-object-server -f overrides.yaml
Verify that our service is exposed with the supplied values:
kubectl describe service foolish-octopus-realm-object-server
... and look for these attributes:
Type: NodePortNodePort: http 30080/TCP
Great! Let's try to access the service with our browser. You should be presented with the Realm Object Server splash screen.
open http://localhost:30080# depending on your configuration you may need to explicitly use IP# For example:open $(minikube ip):30080# depending on the OS you are using, the command may need to be adjusted# For example, if using Kubuntu, you can use:xdg-open $(minikube ip):30080
We can also access Realm Object Server using Realm Studio. The Helm chart contains a default private key, so you can use the following admin token to authenticate to the above URL:
When using a cloud provider such as AWS or GKE, you can use the
LoadBalancer service type to expose Realm Obbject Server to the internet. Here is a basic example of the overrides required to do so:
This override works in GKE, however AWS requires that we set a couple of options in order to properly handle websocket connections:
service:type: LoadBalancerannotations:service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "tcp"service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout: "3600"
realm-object-server Helm chart includes a stats collection option. To enable it, add the following to your
overrides.yaml file (remember, these options are shown and documented in the chart's
prometheus:enabled: truegrafana:enabled: true# You can also configure the service and/or ingress, just as with# core services:service:type: NodePortport: 30081
This will ensure that Prometheus is installed alongside Realm Object Server. It will be configured to scrape Realm Object Server periodically for stats, which can be viewed in Grafana. The Grafana installation includes a few canned dashboards that are preconfigured to view these metrics.