OpenCost on AWS

Use this guide to deploy OpenCost components for Kubernetes Billing exports to Amazon S3.

Prerequisites

Before you begin, make sure you have:

• Infrastructure & permissions
  • An Amazon EKS cluster
  • Cluster administrator access
• Required tools
  • AWS CLI (aws)
  • kubectl
  • Helm (v3.x or later)

Set Up an S3 Bucket

Create an S3 bucket for OpenCost Parquet exports:

1. In the AWS console, navigate to the S3 console.
2. Click Create bucket.
3. Set Bucket name, for example, opencost-exports. The bucket name must be unique.
4. Leave the default settings as is and click Create bucket.

Additional requirements:

• Create the bucket in the same AWS Region as the EKS cluster.
• Update the Cloudaware billing policy in your AWS account to allow access to this bucket.

note

Use the bucket name consistently in the later steps.

Configure IAM Role for Service Account (IRSA)

Create an IAM role that the OpenCost pod will assume to write data to S3.

Retrieve Your Cluster’s OIDC Provider URL

1. Navigate to the Amazon EKS console → Clusters and select your cluster.
2. On the Overview tab under Details, find OpenID Connect provider URL and note the value.

Create the IAM Policy

This policy grants permission for OpenCost to write to your S3 bucket.

1. Open the IAM console. Go to Policies → Create policy.

2. Switch to the JSON tab and paste the following policy, replacing {YOUR_OPENCOST_S3_BUCKET_NAME} with your S3 bucket name:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Action": ["s3:PutObject", "s3:GetObject"],
         "Effect": "Allow",
         "Resource": "arn:aws:s3:::{YOUR_OPENCOST_S3_BUCKET_NAME}/*"
       }
     ]
   }

3. Name the policy opencost-s3-policy, then create it.

Create the IAM Role

1. In the IAM console, go to Roles → Create role.
2. For Trusted entity type, select Web identity.
3. For Identity provider, choose the OIDC provider retrieved earlier (for example, oidc.eks.us-east-1.amazonaws.com/id/YOUR_OIDC_ID).
4. For Audience, use sts.amazonaws.com.
5. Add a condition so that only the OpenCost service account can assume this role:
   • Key: your EKS OIDC provider.
   • Condition: StringEquals.
   • Value: system:serviceaccount:opencost:opencost-aws.
6. Attach the opencost-s3-policy policy created in the previous step.
7. Name the role opencost-eks-role, then create it.

Deploy Prometheus

tip

If you use an external Prometheus instance, skip this step and review the Configuration notes (1) for external Prometheus below.

1. Add the Prometheus Helm repository:

   helm repo add prometheus-community https://prometheus-community.github.io/helm-charts

2. Create the Prometheus namespace:

   kubectl create namespace prometheus-system

3. Install Prometheus:

   helm install prometheus prometheus-community/prometheus \
     --namespace prometheus-system \
     --set prometheus-pushgateway.enabled=false \
     --set alertmanager.enabled=false

Deploy OpenCost

1. Add the OpenCost Helm repository:

   helm repo add opencost https://opencost.github.io/opencost-helm-chart

2. Create the OpenCost namespace:

   kubectl create namespace opencost

3. Install OpenCost with an IRSA-enabled service account. Replace {YOUR_IAM_ROLE_ARN} with the ARN of the opencost-eks-role (for example, arn:aws:iam::123456789012:role/opencost-eks-role):

   helm --namespace opencost install opencost opencost/opencost -f - <<EOF
   serviceAccount:
     create: true
     name: opencost-aws
     annotations:
       eks.amazonaws.com/role-arn: "{YOUR_IAM_ROLE_ARN}"
   opencost:
     prometheus:
       namespaceName: prometheus-system
   podAnnotations:
     prometheus.io/path: /metrics
     prometheus.io/port: "9003"
     prometheus.io/scrape: "true"
   EOF

   tip

   The podAnnotations ensure that Prometheus scrapes metrics from the OpenCost pods, enabling label‑based metadata in reports.

Configuration Notes

1. If your cluster already has an external Prometheus, configure OpenCost to use the existing Prometheus instance by setting the following Helm values. Replace {YOUR_PROMETHEUS_URL} with the correct endpoint:

   opencost:
     prometheus:
       external:
         enabled: true
         url: {YOUR_PROMETHEUS_URL}

2. If your cluster uses prometheus-operator, enable ServiceMonitor; otherwise OpenCost metrics will not be scraped automatically:

   opencost:
     metrics:
       serviceMonitor:
         enabled: true

Deploy the Parquet Exporter

Install the component that exports OpenCost data to S3. The same service account (opencost-aws) is reused.

• To store reports in subfolders or use a naming prefix, use the command below, replacing {YOUR_CLUSTER_PREFIX}, {YOUR_OPENCOST_S3_BUCKET_NAME} and {YOUR_CLUSTER_ARN} with the appropriate values:

  helm install parquet-exporter opencost/opencost-parquet-exporter \
    --namespace opencost \
    --set schedule="0 */12 * * *" \
    --set existingServiceAccount=opencost-aws \
    --values - <<EOF
  resources:
    limits:
      cpu: "1"
      memory: 1Gi
    requests:
      cpu: 100m
      memory: 100Mi
  securityContext: null
  env:
    - name: OPENCOST_PARQUET_SVC_HOSTNAME
      value: "opencost.opencost.svc.cluster.local"
    - name: OPENCOST_PARQUET_STORAGE_BACKEND
      value: "aws"
    - name: OPENCOST_PARQUET_S3_BUCKET
      value: "{YOUR_OPENCOST_S3_BUCKET_NAME}"
    - name: OPENCOST_PARQUET_FILE_KEY_PREFIX
      value: "{YOUR_CLUSTER_PREFIX}/{YOUR_CLUSTER_ARN}"
    - name: OPENCOST_PARQUET_JSON_SEPARATOR
      value: "_"
  EOF

• To store reports in the root folder, use this variant instead, replacing {YOUR_OPENCOST_S3_BUCKET_NAME} and {YOUR_CLUSTER_ARN} with the appropriate values:

  helm install parquet-exporter opencost/opencost-parquet-exporter \
    --namespace opencost \
    --set schedule="0 */12 * * *" \
    --set existingServiceAccount=opencost-aws \
    --values - <<EOF
  resources:
    limits:
      cpu: "1"
      memory: 1Gi
    requests:
      cpu: 100m
      memory: 100Mi
  securityContext: null
  env:
    - name: OPENCOST_PARQUET_SVC_HOSTNAME
      value: "opencost.opencost.svc.cluster.local"
    - name: OPENCOST_PARQUET_STORAGE_BACKEND
      value: "aws"
    - name: OPENCOST_PARQUET_S3_BUCKET
      value: "{YOUR_OPENCOST_S3_BUCKET_NAME}"
    - name: OPENCOST_PARQUET_FILE_KEY_PREFIX
      value: "{YOUR_CLUSTER_ARN}"
    - name: OPENCOST_PARQUET_JSON_SEPARATOR
      value: "_"
  EOF

warning

For multi‑cluster environments, deploy the Parquet exporter separately on each cluster.

Verify the Deployment

1. Verify that all pods are running:

   kubectl get pods -n prometheus-system
   kubectl get pods -n opencost

2. Access the OpenCost UI using port‑forwarding:

   kubectl port-forward -n opencost service/opencost 9090:9090

Then open http://localhost:9090 in your browser.

note

The first Parquet export may take up to 24 hours. To verify the export, check your S3 bucket for newly created Parquet files.

Next Steps

Return to the parent guide Kubernetes Billing (OpenCost) to proceed with the Kubernetes Billing setup in Cloudaware.