Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Set up a GEL cluster

Set up GEL on AWS Marketplace

Enterprise

Set up Grafana Enterprise Logs on AWS Marketplace

Grafana Enterprise Logs (GEL) on AWS Marketplace offers a simple and easy way to get production grade GEL clusters up and running in your own Amazon Elastic Kubernetes Service (EKS) cluster.

This procedure guides you through the process of deploying GEL through the AWS Marketplace.

Prerequisites

In order to complete the steps described in this guide, we require that:

You have access to an AWS account with sufficient permissions to subscribe to products on the AWS Marketplace.
You have a properly sized, correctly configured and running EKS cluster (Kubernetes 1.18 or greater), as well as sufficient permissions to create an IAM role and policy for your service account (using aws-cli and/or eksctl).
You have Helm (3.6.0 or newer), the latest version of the AWS Command Line Interface and kubectl installed on your local machine pointing to the correct EKS cluster.

Log in to your AWS account.
Subscribe to the Grafana Enterprise Logs product on the AWS Marketplace; go to the product overview page, and click the Continue to Subscribe button in the top-right corner of the page.
Accept the terms and conditions by selecting the Accept Terms button.
After the process of subscribing completes, from the top-right corner of the page, select Continue to Configuration.
From the Delivery Method drop-down menu on Configure this software page, select “Helm Chart”.
From the Software Version drop-down menu, select a version.
In the upper-right corner, select Continue to Launch. The Launch this software page displays and your subscription set-up process is complete for the Grafana Enterprise Logs product.
Select Usage Instructions.

Step 2. Prepare your Kubernetes cluster

Create a Kubernetes namespace for your application using the kubectl command.
sh
```
kubectl create namespace NAMESPACE_NAME
```
where NAMESPACE_NAME is the name you have chosen for your GEL cluster’s namespace.

Create the image pull secret for the Amazon Elastic Container Registry (ECR).

# get login credentials from AWS and store them in config.json
aws ecr get-login-password --region us-east-1 | docker --config . login --username AWS --password-stdin 709825985650.dkr.ecr.us-east-1.amazonaws.com
# use config.json to create a Kubernetes image pull secret
kubectl --namespace NAMESPACE_NAME create secret generic ecr --from-file=.dockerconfigjson=config.json --type=kubernetes.io/dockerconfigjson

where NAMESPACE_NAME is the name of the namespace from the previous step.

Set up a Kubernetes service account, to allow a container in your EKS cluster to communicate with AWS services.
For that, create an IAM policy that specifies the required permissions, and attach the policy to a role that is associated with the Kubernetes ServiceAccount under which the Pod runs.
There are multiple ways to create the policy and the role. We recommend following the steps of the Amazon EKS User Guide using eksctl. For the --name parameter of the eksctl create iamserviceaccount command, use marketplace-service-account as its value. This value will be referenced later when configuring the Helm chart.
GEL utilizes the Marketplace Metering APIs to check whether your AWS account is subscribed to the Marketplace product and to report usage for billing. Therefore the Pod requires permissions for RegisterUsage and MeterUsage.
GEL also uses Amazon S3 as the storage backend for TSDB blocks and other meta information.
An example policy contains the required permissions:
json
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "aws-marketplace:RegisterUsage",
        "aws-marketplace:MeterUsage"
      ],
      "Effect": "Allow",
      "Resource": "*"
    },
    {
      "Action": [
        "s3:*"
      ],
      "Effect": "Allow",
      "Resource": [
        "arn:aws:s3:::<admin-bucket>",
        "arn:aws:s3:::<admin-bucket>/*",
        "arn:aws:s3:::<ruler-bucket>",
        "arn:aws:s3:::<ruler-bucket>/*",
        "arn:aws:s3:::<tsdb-bucket>",
        "arn:aws:s3:::<tsdb-bucket>/*"
      ]
    }
  ]
}
```
Warning: If you do not grant the permissions above your Grafana Enterprise Logs installation will not function. Even though some services will continue to run, others won’t start, and any enterprise features are disabled; only Loki functionality will be available.

Step 3. Prepare a Helm chart

Be aware that as part of the Grafana Enterprise Logs Helm chart, many different pods and services are installed which all have varying resource requirements. Ensure that you have sufficient resources (both CPU and memory) available in your EKS cluster or auto-scaling enabled before installing the software stack.

Add the Grafana Helm repository and update, so you have the most recent versions of the charts.

helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

The output should match your EKS cluster environment.

Step 4. Save GEL cluster configuration

To account for different ingestion and querying requirements, the Helm chart can be configured to scale services horizontally by the amount of replicas and vertically by the amount of compute resources in form of CPU and memory requests and limits.

If you are unsure about sizing, use the small.yaml configuration from https://github.com/grafana/helm-charts/blob/main/charts/enterprise-logs/small.yaml.

In addition to the scale values file, you need a local file that contains the AWS Marketplace license configuration and the custom S3 configuration for the storage backends. Save this YAML configuration in a local file; this example uses the file name custom.yaml:

# -- Definition of the Docker image for Grafana Enterprise Logs
# If any of these values are changed, then they also need to be reflected in
# `loki-distributed.loki.image`
image: &image
  # -- The container registry to use
  registry: 709825985650.dkr.ecr.us-east-1.amazonaws.com
  # -- The image repository to use
  repository: grafana-labs/grafana-enterprise-logs
  # -- The version of Grafana Enterprise Logs
  tag: v1.2.0
  # -- Additional image pull secrets
  pullSecrets:
    - ecr

# -- Definition of the ServiceAccount for containers
# Any additional configuration of the ServiceAccount has to be done in
# `loki-distributed.serviceAccount`.
serviceAccount: &serviceAccount
  # -- Specifies whether a ServiceAccount should be created
  # If this value is changed to `false`, it also needs to be reflected in
  # `loki-distributed.serviceAccount.create`.
  create: false
  name: marketplace-service-account

loki-distributed:
  loki:
    image: *image
  serviceAccount: *serviceAccount

# -- Grafana Enterprise Logs configuration file
config:
  license:
    type: aws-marketplace
  admin_client:
    storage:
      type: "s3"
      s3:
        endpoint: "s3.amazonaws.com"
        region: "<region>"
        bucket_name: "<admin-bucket>"
        secret_access_key: null
        access_key_id: null
        insecure: false
  storage_config:
    aws:
      endpoint: "s3.amazonaws.com"
      region: "<region>"
      bucketnames: "<tsdb-bucket>"
      bucket_name: "<admin-bucket>"
      secret_access_key: null
      access_key_id: null
      insecure: false
  ruler:
    storage:
      type: s3
      s3:
        endpoint: "s3.amazonaws.com"
        region: "<region>"
        bucket_name: "<ruler-bucket>"
        secret_access_key: null
        access_key_id: null
        insecure: false

You need to provide the admin-bucket, tsdb-bucket, ruler-bucket, and region configuration. Configure GEL to use different buckets for storing administration objects (admin_client), TSDB blocks (storage_config) and rules (ruler_storage).

Replace image.tag and loki-distributed.loki.image.tag with the GEL version that you selected in the final step of the Marketplace subscription flow.

Step 5. Deploy the GEL cluster using Helm

Pass your customized YAML configuration in the helm install command. This example uses custom.yaml as the file name:

helm --kube-context CONTEXT \
    install NAME \
    grafana/enterprise-logs \
    --namespace NAMESPACE_NAME \
    --values SMALL_CONFIG \
    --values custom.yaml

where CONTEXT points to your desired EKS cluster, NAME is your chosen name for the deployment, and NAMESPACE_NAME is the namespace you assigned for your GEL cluster. SMALL_CONFIG can be https://raw.githubusercontent.com/grafana/helm-charts/main/charts/enterprise-logs/small.yaml, or the path to a local small.yaml file if you downloaded the file and saved it locally.

After deploying your GEL cluster, it can take a few minutes before all of the services are running. To verify that your deploy succeeded, watch the rollout of the pods of deployments and statefulsets.

The AWS Marketplace version of Grafana Enterprise Logs does not contain a web-based frontend. To have a web-based frontend, install Grafana Enterprise and the GEL plugin.

Billing

The GEL product is billed by consumption with a single usage dimension “CPU time”. CPU time is defined by the amount of provisioned CPU cores (value of GOMAXPROCS as exposed by Prometheus metric cortex_quota_gomaxprocs) times the hours that the product is running. Each Pod that runs as part of the product contributes to the overall usage, meaning that scaling up will also result in higher consumption.

The minimum CPU per container is 1, even if Kubernetes resource limits are set to a fraction of a CPU (below 1000m) for a Pod. If you don’t set any CPU resource limits on containers, GEL will use the number of physical CPU cores as reported by Golang’s GOMAXPROCS. If Kubernetes resource limits are set, GOMAXPROCS is automatically set to the next highest integer value of the CPU limit. If you do not want to set CPU limits on Kubernetes (kernel level), but still want to limit CPU usage, you can still override the GOMAXPROCS value by providing the GOMAXPROCS environment variable in the Helm chart deployment.