added grafana solution docs

tjfontaine · Mar 1, 2019 · 2f31118 · 2f31118
1 parent ea72f51
commit 2f31118
Show file tree

Hide file tree

Showing 65 changed files with 519 additions and 0 deletions.
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.23.46 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.23.46 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.23.54 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.23.54 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.02 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.02 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.13 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.13 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.17 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.17 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.24 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.24 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.29 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.24.29 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.25.33 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.25.33 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.01 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.01 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.18 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.18 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.23 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.23 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.26 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.26.26 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.27.53 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.27.53 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.58.23 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.58.23 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.59.38 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 3.59.38 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.01.34 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.01.34 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.01.47 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.01.47 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.04.42 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-17 at 4.04.42 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 1.57.02 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 1.57.02 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 2.58.59 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 2.58.59 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 3.00.10 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 3.00.10 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 3.02.31 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 3.02.31 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 4.18.19 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 4.18.19 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 4.18.32 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 4.18.32 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 5.20.58 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-19 at 5.20.58 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.17.47 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.17.47 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.18.08 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.18.08 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.19.08 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.19.08 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.19.14 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.19.14 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.20.23 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.20.23 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.21.07 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.21.07 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.21.52 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.21.52 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.22.47 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.22.47 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.23.15 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.23.15 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.24.12 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2018-12-20 at 2.24.12 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.00.28 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.00.28 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.02.33 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.02.33 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.02.36 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.02.36 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.03.04 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.03.04 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.03.38 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.03.38 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.05.13 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.05.13 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.10.49 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.10.49 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.15.05 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.15.05 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.18.44 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.18.44 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.18.51 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.18.51 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.47 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.47 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.51 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.51 PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.58 PM.png b/...-and-analysis/telemetry/grafana/images/Screen Shot 2019-01-11 at 3.19.58 PM.png
diff --git a/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 10.32.32 AM.png b/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 10.32.32 AM.png
diff --git a/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 11.11.50 AM.png b/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 11.11.50 AM.png
diff --git a/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 11.21.19 AM.png b/...and-analysis/telemetry/grafana/images/Screen Shot 2019-01-13 at 11.21.19 AM.png
diff --git a/...and-analysis/telemetry/grafana/images/Screen Shot 2019-02-14 at 12.03.26 PM.png b/...and-analysis/telemetry/grafana/images/Screen Shot 2019-02-14 at 12.03.26 PM.png
diff --git a/...and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-08_at_10.19.56_AM.png b/...and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-08_at_10.19.56_AM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_2.53.37_PM.png b/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_2.53.37_PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_2.59.47_PM.png b/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_2.59.47_PM.png
diff --git a/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_3.06.49_PM.png b/...-and-analysis/telemetry/grafana/images/Screen_Shot_2019-02-15_at_3.06.49_PM.png
diff --git a/observability-and-analysis/telemetry/grafana/images/templating.gif b/observability-and-analysis/telemetry/grafana/images/templating.gif
diff --git a/observability-and-analysis/telemetry/grafana/kubernetes.md b/observability-and-analysis/telemetry/grafana/kubernetes.md
@@ -0,0 +1,80 @@
+# Oracle Kubernetes Engine Installation - Oracle Cloud Infrastructure Data Source for Grafana
+
+## Pre-requisites:
+
+* [Oracle Container Engine for Kubernetes (OKE)](http://www.oracle.com/webfolder/technetwork/tutorials/obe/oci/oke-full/index.html)
+* [Kubectl 1.7.4](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+* [Helm](https://github.com/kubernetes/helm#install) 
+
+## Background
+
+Grafana is a popular technology that makes it easy to visualize metrics. The [Oracle Cloud Infrastructure Data Source for Grafana](https://grafana.com/plugins/oci-datasource) is used to extend Grafana by adding OCI as a data source. The plugin enables you to visualize metrics related to a number of OCI resources: Compute, Networking, Storage, and custom metrics.
+
+This walkthrough is intended for use by people who would like to deploy Grafana and the OCI Data Source for Grafana on a Kubernetes environment.
+
+## Configuring the OCI Identity policies
+
+In order to use the the OCI Data Source for Grafana on OKE, the first step is to create a [dynamic group](https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingdynamicgroups.htm) used to group virtual machine or bare metal compute instances as “principals” (similar to user groups). Create a dynamic group that corresponds to all of your OKE worker nodes:
+
+   ![Screen Shot 2018-12-17 at 4.01.34 PM](images/Screen%20Shot%202018-12-17%20at%204.01.34%20PM.png)
+
+Next, create a [policy](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policygetstarted.htm) named “grafana_policy” in the root compartment of your tenancy to permit instances in the dynamic group to make API calls against Oracle Cloud Infrastructure services. Add the following policy statements:
+
+* `allow group grafana to read metrics in tenancy`
+* `allow group grafana to read compartments in tenancy`
+
+   ![Screen Shot 2018-12-17 at 4.01.47 PM](images/Screen%20Shot%202018-12-17%20at%204.01.47%20PM.png)
+
+
+## The Grafana Helm chart
+
+Next, we are going to install the stable Helm chart for Grafana. We will do this in two parts: First, update the stable repository by running: `helm repo update`
+
+Next, install the stable chart for Grafana. To do this run: `helm install --name grafana stable/grafana`
+
+We can now make a change to the deployment that was created for Grafana by running `kubectl edit deployment grafana`, and adding an additional environment variable to the Grafana contianer which will download the plugin. After saving the deployment, the changes will be reflected with a new pod.
+
+```
+        - name: GF_INSTALL_PLUGINS
+          value: oci-datasource
+```
+
+## Accessing Grafana
+
+To see if everything is working correctly, access Grafana using Kubernetes port-forwarding. To do this run: `export POD_NAME=$(kubectl get pods --namespace default -l "app=grafana,release=grafana" -o jsonpath="{.items[0].metadata.name}")`
+
+Followed by: `kubectl --namespace default port-forward $POD_NAME 3000`
+
+You can obtain the password for the admin user by running: `kubectl get secret --namespace default grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo`
+
+## Configure Grafana
+
+The next step is to configure the plugin. Navigate to the Grafana homepage at `http://localhost:3000`
+
+![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
+
+Log in with the default username `admin` and the password you obtained from the kubectl command from the previous section.
+
+On the Home Dashboard click the gear icon on the left side of the page.
+
+![Screen Shot 2018-12-17 at 3.24.02 PM](images/Screen%20Shot%202018-12-17%20at%203.24.02%20PM.png)
+
+Click **Add data source**.
+
+![Screen Shot 2018-12-17 at 3.24.13 PM](images/Screen%20Shot%202018-12-17%20at%203.24.13%20PM.png)
+
+ Choose **oracle-oci-datasource** as your data source type.
+
+![Screen Shot 2018-12-17 at 3.24.24 PM](images/Screen%20Shot%202018-12-17%20at%203.24.17%20PM.png)
+
+Fill in your **Tenancy OCID**, **Default Region**, and **Environment**. Your **Default region** is the same as your home region listed in the **Tenancy Details** page. For **Environment** choose **OCI Instance**. 
+
+Click **Save & Test** to return to the home dashboard.
+
+![Screen Shot 2018-12-17 at 3.25.33 PM](images/Screen_Shot_2019-02-08_at_10.19.56_AM.png)
+
+## Next Steps
+
+Check out how to use the newly installed and configured plugin in our [Using Grafana with Oracle Cloud Infrastructure Data Source](docs/Using%20Grafana%20with%20the%20Oracle%20Cloud%20Infrastructure%20Data%20Source.md) walkthrough. 
+
+
diff --git a/observability-and-analysis/telemetry/grafana/linux.md b/observability-and-analysis/telemetry/grafana/linux.md
@@ -0,0 +1,72 @@
+# Local Installation (Linux) - Oracle Cloud Infrastructure Data Source for Grafana 
+
+## Background
+
+Grafana is a popular technology that makes it easy to visualize metrics. The Oracle Cloud Infrastructure Data Source for Grafana is used to extend Grafana by adding OCI as a data source. The plugin enables you to visualize metrics related to a number of OCI resources: Compute, Networking, Storage, and custom metrics. 
+
+This walkthrough is intended for use by people who would like to deploy Grafana and the OCI Data Source for Grafana on a local server. 
+
+## Install the Oracle Cloud Infrastructure CLI 
+
+The [Oracle Cloud Infrastructure CLI](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/cliconcepts.htm) provides you with a way to perform tasks in OCI from your command line rather than the OCI Console. It does so by making REST calls to the [OCI APIs](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/usingapi.htm). We will be using the CLI to authenticate between our local environment hosting Grafana and OCI in order to pull in metrics. The CLI is built on Python (version 2.7.5 or 3.5 or later), running on Mac, Windows, or Linux.
+
+Begin by [installing the Oracle Cloud Infrastructure CLI](https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliinstall.htm). Follow the installation prompts to install the CLI on your local environment. After the installation is complete, use the `oci setup config` command to have the CLI walk you through the first-time setup process. If you haven't already uploaded your public API signing key through the console, follow the instructions [here](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm#How2) to do so. 
+
+## Configure OCI Identity Policies
+
+In the OCI console under **Identity > Groups** click **Create Group** and create a new group called **grafana**. Add the user configured in the OCI CLI to the newly-created group. 
+
+![Screen Shot 2018-12-19 at 3.02.31 PM](images/Screen%20Shot%202018-12-19%20at%203.02.31%20PM.png)
+
+Under the **Policy** tab click **Create Policy** and create a policy allowing the group to read tenancy metrics. Add the following policy statements:
+
+- `allow group grafana to read metrics in tenancy`
+- `allow group grafana to read compartments in tenancy`
+
+![Screen Shot 2018-12-19 at 3.00.10 PM](images/Screen%20Shot%202018-12-19%20at%203.00.10%20PM.png)
+
+## Install Grafana and the OCI Data Source for Grafana Plugin 
+
+To [install the data source](https://grafana.com/plugins/oci-datasource/installation) make sure you are running [Grafana 3.0](https://grafana.com/get) or later. Use the [grafana-cli tool](http://docs.grafana.org/plugins/installation/) to install the Oracle Cloud Infrastructure Data Source for Grafana from the command line:
+
+```
+grafana-cli plugins install oci-datasource
+```
+
+The plugin will be installed into your Grafana plugins directory, which by default is located at /var/lib/grafana/plugins. [Here is more information on the CLI tool](http://docs.grafana.org/plugins/installation/). Alternatively, you can manually download the .zip file and unpack it into your /grafana/plugins directory. To do so, change to the Grafana plugins directory: `cd /usr/local/var/lib/grafana/plugins`. Download the OCI Grafana Plugin: wget `https://grafana.com/api/plugins/oci-datasource/versions/1.0.0/download`. Create a directory and install the plugin: `mkdir oci && tar -C oci -xvf plugin.tar` and then remove the tarball: `rm plugin.tar`. 
+
+To start the Grafana server, run: `sudo systemctl start grafana-server`. 
+
+Navigate to the Grafana homepage at http://localhost:3000.
+
+
+## Configure Grafana
+
+![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
+
+Log in with the default username `admin` and the password `admin`. You will be prompted to change your password. Click **Skip** or **Save** to continue. 
+
+![Screen Shot 2018-12-17 at 3.23.54 PM](images/Screen%20Shot%202018-12-17%20at%203.23.54%20PM.png)
+
+On the Home Dashboard click the gear icon on the left side of the page.
+
+![Screen Shot 2018-12-17 at 3.24.02 PM](images/Screen%20Shot%202018-12-17%20at%203.24.02%20PM.png)
+
+Click **Add data source**.
+
+![Screen Shot 2018-12-17 at 3.24.13 PM](images/Screen%20Shot%202018-12-17%20at%203.24.13%20PM.png)
+
+ Choose **oracle-oci-datasource** as your data source type.
+
+![Screen Shot 2018-12-17 at 3.24.24 PM](images/Screen%20Shot%202018-12-17%20at%203.24.17%20PM.png)
+
+Fill in your **Tenancy OCID**, **Default Region**, and **Environment**. For **Environment** choose **local**. 
+
+Click **Save & Test** to return to the home dashboard.
+
+![Screen Shot 2018-12-17 at 3.25.33 PM](images/Screen%20Shot%202018-12-17%20at%203.25.33%20PM.png)
+
+## Next Steps
+
+Check out how to use the newly installed and configured plugin in our [Using Grafana with Oracle Cloud Infrastructure Data Source](docs/Using%20Grafana%20with%20the%20Oracle%20Cloud%20Infrastructure%20Data%20Source.md) walkthrough. 
+
diff --git a/observability-and-analysis/telemetry/grafana/linuxoci.md b/observability-and-analysis/telemetry/grafana/linuxoci.md
@@ -0,0 +1,67 @@
+# OCI Virtual Machine Installation - Oracle Cloud Infrastructure Data Source for Grafana   
+
+## Background
+
+Grafana is a popular technology that makes it easy to visualize metrics. The Oracle Cloud Infrastructure Data Source for Grafana is used to extend Grafana by adding OCI as a data source. The plugin enables you to visualize metrics related to a number of OCI resources: Compute, Networking, Storage, and custom metrics. 
+
+This walkthrough is intended for use by people who would like to deploy Grafana and the OCI Data Source for Grafana on a virtual machine in OCI. 
+
+## Create the Grafana Environment in OCI 
+
+Provision an Oracle Linux [virtual machine](https://docs.cloud.oracle.com/iaas/Content/Compute/Concepts/computeoverview.htm) in OCI connected to a [Virtual Cloud Network](https://docs.cloud.oracle.com/iaas/Content/Network/Tasks/managingVCNs.htm) with access to the public internet. If you do not already have access to a Virtual Cloud Network with access to the public internet you can navigate to **Virtual Cloud Networks** under **Networking** and click **Create Virtual Cloud Network**. Choosing the `CREATE VIRTUAL CLOUD NETWORK PLUS RELATED RESOURCES` option will result in a VCN with an Internet Routing Gateway and Route Tables configured for access to the public internet. Three subnets will be created: one in each availability domain in the region.
+
+After creating your VM, the next step is to create a [dynamic group](https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managingdynamicgroups.htm) used to group virtual machine or bare metal compute instances as “principals” (similar to user groups). 
+
+   ![Screen Shot 2018-12-17 at 4.01.34 PM](images/Screen%20Shot%202018-12-17%20at%204.01.34%20PM.png)
+
+Next, create a [policy](https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policygetstarted.htm) named “grafana_policy” in the root compartment of your tenancy to permit instances in the dynamic group to make API calls against Oracle Cloud Infrastructure services. Add the following policy statements:
+
+* `allow group grafana to read metrics in tenancy`
+* `allow group grafana to read compartments in tenancy`
+
+   ![Screen Shot 2018-12-17 at 4.01.47 PM](images/Screen%20Shot%202018-12-17%20at%204.01.47%20PM.png)
+
+## Install Grafana and the OCI Data Source for Grafana Plugin 
+
+To [install the data source](https://grafana.com/plugins/oci-datasource/installation) make sure you are running [Grafana 3.0](https://grafana.com/get) or later. Use the [grafana-cli tool](http://docs.grafana.org/plugins/installation/) to install the Oracle Cloud Infrastructure Data Source for Grafana from the command line:
+
+```
+grafana-cli plugins install oci-datasource
+```
+
+The plugin will be installed into your Grafana plugins directory, which by default is located at /var/lib/grafana/plugins. [Here is more information on the CLI tool](http://docs.grafana.org/plugins/installation/). Alternatively, you can manually download the .zip file and unpack it into your /grafana/plugins directory. To do so, change to the Grafana plugins directory: `cd /usr/local/var/lib/grafana/plugins`. Download the OCI Grafana Plugin: wget `https://grafana.com/api/plugins/oci-datasource/versions/1.0.0/download`. Create a directory and install the plugin: `mkdir oci && tar -C oci -xvf plugin.tar` and then remove the tarball: `rm plugin.tar`. 
+
+To start the Grafana server, run: `sudo systemctl start grafana-server`. 
+
+
+## Configure Grafana
+
+The next step is to configure the plugin. To find the IP address of the newly-created instance, navigate to Compute > Instances > [Your Instance]. The Public IP address is listed under the Primary VNIC Information section. Connect to Grafana via port forward by running `ssh opc@[Instance Public IP] -L 3000:localhost:3000`. 
+
+Navigate to the Grafana homepage at http://localhost:3000.
+
+![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
+
+Log in with the default username `admin` and the password `admin`. You will be prompted to change your password. Click **Skip** or **Save** to continue. ![Screen Shot 2018-12-17 at 3.23.54 PM](images/Screen%20Shot%202018-12-17%20at%203.23.54%20PM.png)
+
+On the Home Dashboard click the gear icon on the left side of the page.
+
+![Screen Shot 2018-12-17 at 3.24.02 PM](images/Screen%20Shot%202018-12-17%20at%203.24.02%20PM.png)
+
+Click **Add data source**.
+
+![Screen Shot 2018-12-17 at 3.24.13 PM](images/Screen%20Shot%202018-12-17%20at%203.24.13%20PM.png)
+
+ Choose **oracle-oci-datasource** as your data source type.
+
+![Screen Shot 2018-12-17 at 3.24.24 PM](images/Screen%20Shot%202018-12-17%20at%203.24.17%20PM.png)
+
+Fill in your **Tenancy OCID**, **Default Region**, and **Environment**. Your **Default region** is the same as your home region listed in the **Tenancy Details** page. For **Environment** choose **OCI Instance**. 
+
+Click **Save & Test** to return to the home dashboard.
+
+![Screen Shot 2018-12-17 at 3.25.33 PM](images/Screen_Shot_2019-02-08_at_10.19.56_AM.png)
+
+## Next Steps
+
+Check out how to use the newly installed and configured plugin in our [Using Grafana with Oracle Cloud Infrastructure Data Source](docs/Using%20Grafana%20with%20the%20Oracle%20Cloud%20Infrastructure%20Data%20Source.md) walkthrough. 
diff --git a/observability-and-analysis/telemetry/grafana/macos.md b/observability-and-analysis/telemetry/grafana/macos.md
@@ -0,0 +1,72 @@
+# Local Installation (MacOS) - Oracle Cloud Infrastructure Data Source for Grafana
+
+## Background
+
+Grafana is a popular technology that makes it easy to visualize metrics. The Oracle Cloud Infrastructure Grafana Plugin is used to extend Grafana by adding OCI as a data source. The plugin enables you to visualize metrics related to a number of OCI resources: Compute, Networking, Storage, and custom metrics. 
+
+This walkthrough is intended for use by people who would like to deploy Grafana and the OCI Data Source for Grafana on a local server. 
+
+## Install the Oracle Cloud Infrastructure CLI 
+
+The [Oracle Cloud Infrastructure CLI](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/cliconcepts.htm) provides you with a way to perform tasks in OCI from your command line rather than the OCI Console. It does so by making REST calls to the [OCI APIs](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/usingapi.htm). We will be using the CLI to authenticate between our local environment hosting Grafana and OCI in order to pull in metrics. The CLI is built on Python (version 2.7.5 or 3.5 or later), running on Mac, Windows, or Linux.
+
+Begin by [installing the Oracle Cloud Infrastructure CLI](https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliinstall.htm). Follow the installation prompts to install the CLI on your local environment. After the installation is complete, use the `oci setup config` command to have the CLI walk you through the first-time setup process. If you haven't already uploaded your public API signing key through the console, follow the instructions [here](https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm#How2) to do so. 
+
+## Configure OCI Identity Policies
+
+In the OCI console under **Identity > Groups** click **Create Group** and create a new group called **grafana**. Add the user configured in the OCI CLI to the newly-created group. 
+
+![Screen Shot 2018-12-19 at 3.02.31 PM](images/Screen%20Shot%202018-12-19%20at%203.02.31%20PM.png)
+
+Under the **Policy** tab switch to the root compartment and click **Create Policy**. Create a policy allowing the group to read tenancy metrics. Add the following policy statements:
+
+- `allow group grafana to read metrics in tenancy`
+- `allow group grafana to read compartments in tenancy`
+
+![Screen Shot 2018-12-19 at 3.00.10 PM](images/Screen%20Shot%202018-12-19%20at%203.00.10%20PM.png)
+
+## Install Grafana and the OCI Data Source for Grafana Plugin 
+
+To [install the data source](https://grafana.com/plugins/oci-datasource/installation) make sure you are running [Grafana 3.0](https://grafana.com/get) or later. On a MacOS system run: `brew install grafana`. Use the [grafana-cli tool](http://docs.grafana.org/plugins/installation/) to install the Oracle Cloud Infrastructure Data Source for Grafana from the command line:
+
+```
+grafana-cli plugins install oci-datasource
+```
+
+The plugin will be installed into your Grafana plugins directory, which by default is located at /var/lib/grafana/plugins. [Here is more information on the CLI tool](http://docs.grafana.org/plugins/installation/). Alternatively, you can manually download the .zip file and unpack it into your /grafana/plugins directory. To do so, change to the Grafana plugins directory: `cd /usr/local/var/lib/grafana/plugins`. Download the OCI Grafana Plugin: wget `https://grafana.com/api/plugins/oci-datasource/versions/1.0.0/download`. Create a directory and install the plugin: `mkdir oci && tar -C oci -xvf plugin.tar` and then remove the tarball: `rm plugin.tar`
+
+To start the Grafana server, run: `brew services start grafana`
+
+Navigate to the Grafana homepage at http://localhost:3000.
+
+
+## Configure Grafana
+
+![Screen Shot 2018-12-17 at 3.23.46 PM](images/Screen%20Shot%202018-12-17%20at%203.23.46%20PM.png)
+
+Log in with the default username `admin` and the password `admin`. You will be prompted to change your password. Click **Skip** or **Save** to continue. 
+
+![Screen Shot 2018-12-17 at 3.23.54 PM](images/Screen%20Shot%202018-12-17%20at%203.23.54%20PM.png)
+
+On the Home Dashboard click the gear icon on the left side of the page.
+
+![Screen Shot 2018-12-17 at 3.24.02 PM](images/Screen%20Shot%202018-12-17%20at%203.24.02%20PM.png)
+
+Click **Add data source**.
+
+![Screen Shot 2018-12-17 at 3.24.13 PM](images/Screen%20Shot%202018-12-17%20at%203.24.13%20PM.png)
+
+ Choose **oracle-oci-datasource** as your data source type.
+
+![Screen Shot 2018-12-17 at 3.24.24 PM](images/Screen%20Shot%202018-12-17%20at%203.24.17%20PM.png)
+
+Fill in your **Tenancy OCID**, **Default Region**, and **Environment**. For **Environment** choose **local**. 
+
+Click **Save & Test** to return to the home dashboard. 
+
+![Screen Shot 2018-12-17 at 3.25.33 PM](images/Screen%20Shot%202018-12-17%20at%203.25.33%20PM.png)
+
+## Next Steps
+
+Check out how to use the newly installed and configured plugin in our [Using Grafana with Oracle Cloud Infrastructure Data Source](docs/Using%20Grafana%20with%20the%20Oracle%20Cloud%20Infrastructure%20Data%20Source.md) walkthrough. 
+