Monitoring AWS

Grafana OSS on AWS User Guide

| Product: Grafana OSS on AWS

Overview

This image runs Grafana OSS, the leading open source observability and dashboarding platform. Grafana connects to dozens of data sources (Prometheus, Loki, InfluxDB, Elasticsearch, PostgreSQL, MySQL, Amazon CloudWatch and many more), turns metrics and logs into rich dashboards, and triggers alerts when something goes wrong.

The image runs Grafana as a systemd service bound to 127.0.0.1:3000, fronted by nginx on port 80. The Grafana port is never exposed directly to the network: customers reach the web user interface on standard HTTP through the nginx reverse proxy. This keeps the network exposure surface down to a single port and means you only have to manage one reverse proxy when you put TLS in front of the deployment.

The Grafana administrator password is generated on the first boot of every deployed instance. Two instances launched from the same Amazon Machine Image never share a password. The image ships without any default or shared credentials; on first boot a systemd one shot service generates a per instance password, rotates the admin user via grafana-cli admin reset-admin-password, and stores the plain text value in /root/grafana-credentials.txt with mode 0600 so that only the root user can read it.

Grafana's data files — the bundled SQLite database, plugins, alerting state and provisioned dashboards — are kept on a dedicated EBS data volume mounted at /var/lib/grafana, separate from the operating system disk, so the data tier can be resized independently of the root volume.

Prerequisites

Before you deploy this image you need:

  • An Amazon Web Services account where you can launch EC2 instances
  • IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
  • An EC2 key pair in the target Region for SSH access to the instance
  • A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound port 80 from the trusted networks that will reach the Grafana web user interface
  • The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Grafana OSS. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network and inbound port 80 from the trusted networks that will reach Grafana. Do not open port 80 to the public internet until you have placed TLS in front of the deployment. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Grafana OSS Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=grafana-01}]'

Wait for the instance to reach the Running state and pass its status checks, then capture the public IPv4 address from aws ec2 describe-instances or the AWS Console.

Step 3: Connecting to your instance

SSH into the instance with the EC2 key pair you specified at launch. The login user depends on the operating system variant of the AMI you subscribed to:

OS variant Login user Example
Ubuntu 24.04 ubuntu ssh -i my-key.pem ubuntu@<public-ip>

Replace my-key.pem with the path to your private key and <public-ip> with the instance's public IPv4 address.

The MOTD banner displayed when you log in confirms the AMI and points at the path of the generated credentials file:

  Grafana OSS on Ubuntu 24.04 (cloudimg AWS Marketplace AMI)
  Retrieve initial admin credentials:  sudo cat /root/grafana-credentials.txt
  User guide:                          https://www.cloudimg.co.uk/guides/grafana-aws/

Step 4: Retrieve the Administrator Password

The Grafana administrator password is unique to the instance you just launched. Read it from the credentials file:

sudo cat /root/grafana-credentials.txt

The file is owned by root with mode 0600, so it is invisible to non root users. You will see a block similar to this:

# Grafana OSS — generated on first boot by grafana-firstboot.service.
# This admin password is unique to this instance. Store it somewhere safe;
# it is shown in plain text only here.

grafana.url=http://<public-ip>/
grafana.admin.user=admin
grafana.admin.pass=<GRAFANA_ADMIN_PASSWORD>

Copy the grafana.admin.pass value into your password manager. The plain text value is only stored here; rotation later in this guide replaces it with a new value.

Step 5: Sign in to the Grafana Web Interface

Open a browser and navigate to http://<public-ip>/. The Grafana sign in page is served by the nginx reverse proxy on port 80; the Grafana upstream is bound to 127.0.0.1:3000 and is never exposed directly to the network.

Grafana sign-in page

Sign in as the admin user with the password from /root/grafana-credentials.txt. Grafana lands you on the Home dashboard with the getting started panels.

Grafana home dashboard

The left hand navigation gives you the main Grafana sections: Dashboards for browsing and creating dashboards, Explore for ad hoc querying, Alerting for the alert rules and contact points, Connections for managing data sources, and Administration for users, teams and server settings.

Step 6: Confirm the Service is Healthy from the Command Line

Grafana exposes a JSON health endpoint at /api/health that requires no authentication. From the instance itself:

curl http://127.0.0.1/api/health

You will see something like:

{
  "database": "ok",
  "version": "12.4.3+security-02",
  "commit": "080f7325"
}

"database": "ok" confirms that Grafana can read and write its bundled SQLite database under /var/lib/grafana/grafana.db.

To check the systemd units directly:

sudo systemctl status grafana-server.service nginx.service grafana-firstboot.service --no-pager

grafana-server.service and nginx.service should be active (running); grafana-firstboot.service should be active (exited) because it is a oneshot that has already completed.

Step 7: Add Your First Data Source

Grafana is most useful when it is connected to a real data source. The image ships with no data sources configured so that your deployment starts in a known state.

In the Grafana web user interface, open the navigation menu and select Connections then Data sources. The page shows the data sources currently connected to the instance; on a fresh deployment the list is empty and Grafana invites you to add the first one.

Grafana data sources page

Click Add data source, pick the data source type that matches the backend you want to query (Prometheus, Loki, InfluxDB, MySQL, PostgreSQL, Amazon CloudWatch, OpenSearch, and many more), and follow the type specific configuration page. Most production deployments connect at least one metrics backend (Prometheus or CloudWatch) and one logs backend (Loki or CloudWatch Logs).

You can also add a data source from the command line using the REST API:

ADMIN_PASS=$(sudo grep '^grafana.admin.pass=' /root/grafana-credentials.txt | cut -d= -f2-)
curl -u admin:"$ADMIN_PASS" -X POST http://127.0.0.1/api/datasources \
     -H 'Content-Type: application/json' \
     -d '{"name":"my-prometheus","type":"prometheus","access":"proxy","url":"http://prometheus.example.internal:9090","isDefault":true}'

A successful response includes "message":"Datasource added".

Step 8: Explore a Data Source

Once you have a data source connected, the Explore view is the fastest way to issue ad hoc queries and look at the results before committing them to a dashboard.

Grafana Explore view

Pick the data source from the dropdown at the top of the Explore page, build a query in the query editor (PromQL for Prometheus, LogQL for Loki, SQL for the relational backends, and so on), and the results render in the graph and table panels below. From there you can save a query into a new or existing dashboard with the Add to dashboard button.

Step 9: Build a Dashboard

From the navigation menu select Dashboards then New then New dashboard. Add a panel, pick a data source, and write the query that drives the panel. Each panel can be a time series chart, table, stat, gauge, bar gauge, pie chart, heatmap, geomap, alert list, log panel or one of many other visualisations.

The image ships with no dashboards, so you start with a clean slate. Save the dashboard with the disk icon in the toolbar; you can also export the JSON model of a dashboard from the dashboard settings and import it on other instances or commit it to source control.

Step 10: Configure an Alert

Grafana's unified alerting lets you trigger notifications when a query result crosses a threshold. From the navigation menu select Alerting then Alert rules then New alert rule.

Pick the data source and the query that returns the metric you want to alert on, set the evaluation threshold and the for duration (how long the threshold must be exceeded before the alert fires), pick a contact point (email, Slack, PagerDuty, OpsGenie, webhook, or one of many other integrations) and save. The alert rule will be evaluated on the schedule you chose and notifications will be delivered when it fires.

Step 11: Install a Plugin

Grafana has a large ecosystem of community plugins for additional data sources, panel types and apps. The image ships with no plugins so that the bundle stays small.

To install a plugin, use the grafana-cli tool from a shell on the instance and restart grafana-server so the new plugin is picked up:

sudo grafana-cli plugins install <plugin-id>
sudo systemctl restart grafana-server.service

A list of all available plugins is at https://grafana.com/grafana/plugins. After the restart, plugins appear under Administration then Plugins and data then Plugins in the web user interface.

Step 12: Rotate the Administrator Password

Rotate the password from the instance command line at any time:

sudo grafana-cli admin reset-admin-password '<new-strong-password>'

Update /root/grafana-credentials.txt to match if you want it to remain the canonical record (it is not consulted at runtime, only by the firstboot service on the very first boot).

You can also rotate the password from the web user interface: sign in as admin, click the user avatar at the bottom of the side bar, select Profile, then Change password.

Step 13: Put TLS in Front of the Deployment

The image serves Grafana over plain HTTP on port 80 by default. For any production deployment you should put TLS in front of the nginx reverse proxy, either by terminating TLS on the instance with a certificate from Let's Encrypt, or by placing the instance behind an AWS Application Load Balancer that handles TLS.

Option A: Terminate TLS on the Instance with Let's Encrypt

Install certbot and request a certificate for the hostname that points at the instance:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

certbot edits the nginx site to listen on 443 with the issued certificate and writes a renewal timer. Update the security group to allow inbound 443 and (optionally) close inbound 80 once the redirect is in place.

Option B: Terminate TLS on an Application Load Balancer

Create an Application Load Balancer, configure a listener on 443 with a certificate from AWS Certificate Manager, and add a target group whose target is the instance on port 80. Update the instance's security group so that inbound 80 is allowed only from the load balancer's security group.

In both cases, set [server] root_url in /etc/grafana/grafana.ini to the public HTTPS URL Grafana is reached on, so that Grafana generates correct absolute URLs in emails and embedded panels, then restart grafana-server:

sudo sed -i 's|^;\?root_url\s*=.*|root_url = https://<your-domain>/|' /etc/grafana/grafana.ini
sudo systemctl restart grafana-server.service

Step 14: Backup and Maintenance

The Grafana state — the bundled SQLite database, plugins, alerting state and provisioned dashboards — all lives under /var/lib/grafana on the dedicated data volume. A snapshot of that volume is a complete backup of your Grafana deployment.

To take a snapshot from the AWS CLI:

VOL=$(aws ec2 describe-instances --instance-ids <instance-id> \
        --query "Reservations[0].Instances[0].BlockDeviceMappings[?DeviceName=='/dev/sdf'].Ebs.VolumeId | [0]" \
        --output text)
aws ec2 create-snapshot --volume-id "$VOL" \
        --description "grafana data $(date -u +%F)"

Schedule a daily snapshot via Amazon Data Lifecycle Manager for hands off backups.

OS security updates are applied by Ubuntu's unattended-upgrades service on the standard schedule. To check the Grafana version itself:

dpkg -l grafana

To pin to a new Grafana 12.x point release, unhold the package, run apt-get update && apt-get install --only-upgrade grafana, and re hold:

sudo apt-mark unhold grafana
sudo apt-get update
sudo apt-get install -y --only-upgrade grafana
sudo apt-mark hold grafana
sudo systemctl restart grafana-server.service

The image holds grafana at the 12.x major to avoid an unattended jump to Grafana 13.x; when you are ready to move major version, unhold the package, run the upgrade, and re hold at the new major.

Step 15: Security Posture Summary

  • The Grafana upstream is bound to 127.0.0.1:3000 only. The Grafana port is never reachable from the network.
  • nginx is the only network exposure surface for Grafana, on port 80.
  • No default or shared credentials ship in the image; every instance generates its own administrator password at first boot, stored at /root/grafana-credentials.txt (mode 0600 root only).
  • SSH host keys, /etc/machine-id and cloud init state are wiped before AMI capture so every customer instance gets a unique identity on first boot.
  • OS security updates are applied automatically by unattended-upgrades.

Where to Get Help

Open a support ticket with cloudimg from your AWS Marketplace subscription page. Include the AMI ID, the instance ID and a description of the issue, and we will respond within the support window stated on the listing. For general Grafana documentation, see https://grafana.com/docs/grafana/latest/.

Screenshots

Grafana sign-in page

The Grafana sign-in page, served on first boot with no manual setup.

Home dashboard

The Grafana home dashboard after sign-in, ready for adding data sources and authoring dashboards.

Data sources page

The Grafana data sources page where customers connect Prometheus, Loki, InfluxDB and many more backends.

Explore view

The Grafana Explore view for ad-hoc querying of any connected data source.