SupportConsoleDevelopersStart a trialContact

Chapter 2. Prepare object storage for LokiStack

After choosing your object storage backend in the Plan section, configure it and create the required Kubernetes secret before creating the LokiStack custom resource.

Important

This section covers object storage preparation procedures. For storage backend selection and requirements planning, see Choose a LokiStack storage backend.

Both block storage and object storage are mandatory:

  • Block storage (StorageClass): For LokiStack internal PVCs (verified in prerequisites)
  • Object storage (S3-compatible): For actual log chunks and indices (configured in this section)

The storageClassName field in the LokiStack CR refers to block storage, NOT object storage. Object storage is configured via the secret referenced in spec.storage.secret.name.

2.1. Object storage permissions requirements
Copy link

The credentials used to access S3-compatible object storage must have specific permissions to allow LokiStack to read, write, and manage log data.

Required S3 API permissions

The following S3 API permissions are required for LokiStack to function correctly:

PermissionPurpose

s3:ListBucket

List objects in the bucket. Required for LokiStack to query and retrieve stored log chunks.

s3:PutObject

Write log chunks and index files to the bucket. Required for log ingestion.

s3:GetObject

Read log chunks and index files from the bucket. Required for log queries and compaction.

s3:DeleteObject

Delete expired log chunks based on retention policies. Required for the compactor component.

s3:GetObjectTagging

Read object tags. Required for retention and lifecycle management.

s3:PutObjectTagging

Write object tags. Required for retention and lifecycle management.

Important

Without s3:DeleteObject permission, the LokiStack compactor cannot remove expired logs. This causes the bucket to grow indefinitely, even when retention policies are configured. The LokiStack shows Ready but old logs are never deleted.

Example IAM policy for AWS S3

If using Amazon S3, create an IAM policy with the following permissions: 

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::<bucket_name>"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:GetObjectTagging",
        "s3:PutObjectTagging"
      ],
      "Resource": "arn:aws:s3:::<bucket_name>/*"
    }
  ]
}

Replace <bucket_name> with your actual S3 bucket name.

Permissions for S3-compatible storage

For S3-compatible storage providers (NetApp StorageGRID, Cloudian HyperStore, and others), ensure the access credentials have equivalent permissions to the S3 API operations listed above. The exact configuration method varies by storage provider.

Consult your storage provider’s documentation for:

  • How to create users or service accounts
  • How to grant S3 API permissions to those accounts
  • Whether additional permissions are required for your specific storage implementation
Note

Some S3 Compatible storage providers use different permission models or naming conventions. Verify that your credentials can perform all six S3 operations listed above.

Additional resources

2.2. Configure a TLS CA bundle for object storage
Copy link

Many on-site and self-signed object storage solutions, such as S3 Compatible storage, Ceph RGW (RADOS Gateway), or Red Hat OpenShift Data Foundation, require a CA bundle so that LokiStack components can trust the storage endpoint.

Important

If your storage uses self-signed or internal certificates and you do not configure the CA bundle, the LokiStack will show Ready but logs will be silently dropped. No error is displayed in the web console.

LokiStack component pods (ingesters, queriers, compactors) will show the following error in their logs: x509: certificate signed by unknown authority

To check for this error, examine the logs of LokiStack component pods by running the following commands: 

$ oc logs -n openshift-logging <lokistack_ingester_pod> | grep -i "x509\|certificate"
$ oc logs -n openshift-logging <lokistack_querier_pod> | grep -i "x509\|certificate"

Prerequisites

  • You have administrator access to the cluster.
  • You have access to the storage backend CA certificate.

Procedure

  1. Extract the CA certificate from your storage provider by running the following command. For example, if using S3 Compatible storage, you can use openssl: 

    $ openssl s_client -connect <storage_endpoint>:<port> -showcerts </dev/null 2>/dev/null | openssl x509 -out storage-ca.crt
    Note

    If you are using OpenShift Data Foundation Ceph RGW (provided by the NooBaa service in Rook deployments), you might need to use the openshift-service-ca.crt from the openshift-service-ca config map.

  2. Create a ConfigMap in the openshift-logging namespace containing the CA certificate by running the following command: 

    $ oc create configmap loki-s3-ca-bundle \
    -n openshift-logging \
    --from-file=ca-bundle.crt=./storage-ca.crt

  3. Reference the CA bundle ConfigMap in your LokiStack custom resource (CR) under spec.storage.tls: 

    apiVersion: loki.storage.openshift.io/v1
kind: LokiStack
metadata:
  name: logging-loki
  namespace: openshift-logging
spec:
  storage:
    schemas:
    - version: v13
      effectiveDate: "2024-10-01"
    secret:
      name: logging-loki-s3
      type: s3
    tls:
      caName: loki-s3-ca-bundle
  storageClassName: <storage_class_name>
  tenants:
    mode: openshift-logging

    The caName field references the ConfigMap created in step 2.

Verification

After creating the LokiStack, verify that component pods can reach the storage endpoint without TLS errors by running the following commands: 

$ oc get pods -n openshift-logging | grep lokistack
$ oc logs -n openshift-logging <lokistack_ingester_pod> | grep -i "error\|x509\|certificate"

A successful configuration shows no certificate verification errors in the logs.

2.3. Configure Amazon S3 for LokiStack
Copy link

As a cluster administrator, you can use Amazon Web Services (AWS) object storage to store logs. Amazon S3 is a well-tested and natively supported backend for LokiStack.

Prerequisites

  • You have an AWS account with permissions to create S3 buckets and IAM policies.
  • You have created an S3 bucket.
  • You have created IAM credentials with the required S3 API permissions. See the object storage permissions requirements.
  • You have cluster administrator permissions.

Procedure

  1. Create an object storage secret with the name logging-loki-aws:

    For standard AWS authentication: 

    $ oc create secret generic logging-loki-aws \
  -n openshift-logging \
  --from-literal=bucketnames="<bucket_name>" \
  --from-literal=endpoint="https://s3.<region>.amazonaws.com" \
  --from-literal=access_key_id="<aws_access_key_id>" \
  --from-literal=access_key_secret="<aws_access_key_secret>" \
  --from-literal=region="<aws_region>"

    + bucketnames:: The name of your S3 bucket.

    endpoint
    The S3 endpoint URL. Use the format https://s3.<region>.amazonaws.com for standard AWS regions.
    region
    The AWS region where your bucket is located (for example, us-east-1).

    For clusters with Security Token Service (STS) enabled: 

    $ oc -n openshift-logging create secret generic logging-loki-aws \
  --from-literal=bucketnames="<s3_bucket_name>" \
  --from-literal=region="<bucket_region>" \
  --from-literal=audience="<oidc_audience>"

    + audience:: Optional OIDC audience annotation. Default value is openshift.

Verification

Run the following command to verify that the secret was created successfully: 

$ oc get secret logging-loki-aws -n openshift-logging

2.4. Configure Azure Blob Storage for LokiStack
Copy link

You can use Azure Blob Storage to store logs in Microsoft Azure.

Prerequisites

  • You have an Azure storage account and a container.
  • You have cluster administrator permissions.

Procedure

  1. Create an object storage secret with the name logging-loki-azure:

    For standard Azure authentication: 

    $ oc create secret generic logging-loki-azure \
  -n openshift-logging \
  --from-literal=container="<azure_container_name>" \
  --from-literal=environment="<azure_environment>" \
  --from-literal=account_name="<azure_account_name>" \
  --from-literal=account_key="<azure_account_key>"

    + environment:: The Azure cloud environment. Supported values are AzureGlobal (commercial Azure), AzureChinaCloud, AzureGermanCloud, or AzureUSGovernment.

    container
    The name of the blob container where logs will be stored.
    account_name
    The name of your Azure storage account.

    For clusters with Microsoft Entra Workload ID enabled: 

    $ oc -n openshift-logging create secret generic logging-loki-azure \
  --from-literal=environment="<azure_environment>" \
  --from-literal=account_name="<storage_account_name>" \
  --from-literal=container="<container_name>"

    +

    Note

    Workload ID authentication does not require account_key because the Cloud Credential Operator (CCO) manages short-term credentials automatically.

Verification

Run the following command to verify that the secret was created successfully: 

$ oc get secret logging-loki-azure -n openshift-logging

2.5. Configure Google Cloud Storage for LokiStack
Copy link

You can use Google Cloud Storage (GCS) to store logs in Google Cloud.

Prerequisites

  • You have a project on Google Cloud.
  • You have created a bucket in the project.
  • You have created a service account with the necessary permissions.
  • You have cluster administrator permissions.

Procedure

  1. Obtain the service account credentials from Google Cloud and save them as key.json.

  2. Create an object storage secret with the name logging-loki-gcs: 

    $ oc create secret generic logging-loki-gcs \
  -n openshift-logging \
  --from-literal=bucketname="<bucket_name>" \
  --from-file=key.json="./key.json"

Verification

Run the following command to verify that the secret was created successfully: 

$ oc get secret logging-loki-gcs -n openshift-logging

You can use Red Hat OpenShift Data Foundation object storage (Ceph RGW / RADOS Gateway) to store logs on site.

Prerequisites

  • You have deployed OpenShift Data Foundation.
  • You have configured your OpenShift Data Foundation cluster for object storage.
  • You have cluster administrator permissions.

Procedure

  1. Create an ObjectBucketClaim custom resource in the openshift-logging namespace: 

    apiVersion: objectbucket.io/v1alpha1
kind: ObjectBucketClaim
metadata:
  name: loki-bucket-odf
  namespace: openshift-logging
spec:
  generateBucketName: loki-bucket-odf
  storageClassName: openshift-storage.noobaa.io
    spec.storageClassName
    Use openshift-storage.noobaa.io for OpenShift Data Foundation NooBaa deployments. This provides the object storage endpoint via Ceph RGW (RADOS Gateway).

  2. Get bucket properties from the associated ConfigMap object: 

    $ BUCKET_HOST=$(oc get -n openshift-logging configmap loki-bucket-odf -o jsonpath='{.data.BUCKET_HOST}')
$ BUCKET_NAME=$(oc get -n openshift-logging configmap loki-bucket-odf -o jsonpath='{.data.BUCKET_NAME}')
$ BUCKET_PORT=$(oc get -n openshift-logging configmap loki-bucket-odf -o jsonpath='{.data.BUCKET_PORT}')

  3. Get bucket access credentials from the associated secret: 

    $ ACCESS_KEY_ID=$(oc get -n openshift-logging secret loki-bucket-odf -o jsonpath='{.data.AWS_ACCESS_KEY_ID}' | base64 -d)
$ SECRET_ACCESS_KEY=$(oc get -n openshift-logging secret loki-bucket-odf -o jsonpath='{.data.AWS_SECRET_ACCESS_KEY}' | base64 -d)

  4. Create an object storage secret with the name logging-loki-odf: 

    $ oc create -n openshift-logging secret generic logging-loki-odf \
  --from-literal=access_key_id="${ACCESS_KEY_ID}" \
  --from-literal=access_key_secret="${SECRET_ACCESS_KEY}" \
  --from-literal=bucketnames="${BUCKET_NAME}" \
  --from-literal=endpoint="https://${BUCKET_HOST}:${BUCKET_PORT}" \
  --from-literal=forcepathstyle="true"

  5. Optional: If your Red Hat OpenShift Data Foundation installation uses self-signed certificates, configure the TLS CA bundle. Follow Configuring a TLS CA bundle for object storage.

    Note

    If using the default Red Hat OpenShift Data Foundation Ceph RGW endpoint (NooBaa service in Rook deployments), you might need to use the service CA certificate.

Verification

Run the following command to verify that the secret was created successfully: 

$ oc get secret logging-loki-odf -n openshift-logging

Additional resources

2.7. Configure S3 Compatible storage for LokiStack
Copy link

You can use any S3 Compatible object storage to store logs. This includes NetApp StorageGRID, Cloudian HyperStore, Hitachi Content Platform (HCP), and other S3-compatible storage providers.

Note

S3 Compatible storage uses different secret parameters than AWS S3. Do not use AWS-specific parameters such as region for S3 Compatible storage.

Prerequisites

  • You have S3 Compatible storage deployed and accessible.
  • You have created a bucket on your S3 Compatible storage.
  • You have created access credentials with the required S3 API permissions. See Object storage permissions requirements.
  • You have cluster administrator permissions.

Procedure

  1. Create an object storage secret with the name logging-loki-s3: 

    $ oc create secret generic logging-loki-s3 \
  -n openshift-logging \
  --from-literal=bucketnames="<bucket_name>" \
  --from-literal=endpoint="<s3_endpoint_url>" \
  --from-literal=access_key_id="<access_key>" \
  --from-literal=access_key_secret="<secret_key>" \
  --from-literal=forcepathstyle="true"
    endpoint
    The full endpoint URL, including protocol and port (for example, https://s3.example.com:9000). Do NOT include the bucket name in the endpoint.
    forcepathstyle
    The forcepathstyle="true" parameter is required for S3 Compatible storage. This is NOT used for AWS S3.

  2. If your S3 Compatible storage uses self-signed certificates or an internal CA, configure the TLS CA bundle. Follow Configuring a TLS CA bundle for object storage.

    Important

    Skipping the CA bundle configuration when using self-signed certificates causes logs to be silently dropped. The LokiStack shows Ready but logs are not stored.

Verification

Verify the secret was created successfully: 

$ oc get secret logging-loki-s3 -n openshift-logging

Additional resources

2.8. Configure Swift storage for LokiStack
Copy link

You can use OpenStack Swift as an object storage backend for LokiStack log storage.

Prerequisites

  • You have an OpenStack environment with Swift deployed.
  • You have created a container on Swift.
  • You have cluster administrator permissions.

Procedure

  1. Create an object storage secret with the name logging-loki-swift: 

    $ oc -n openshift-logging create secret generic logging-loki-swift \
  --from-literal=auth_url="<swift_auth_url>" \
  --from-literal=username="<swift_username>" \
  --from-literal=user_domain_name="<swift_user_domain_name>" \
  --from-literal=user_domain_id="<swift_user_domain_id>" \
  --from-literal=user_id="<swift_user_id>" \
  --from-literal=password="<swift_password>" \
  --from-literal=domain_id="<swift_domain_id>" \
  --from-literal=domain_name="<swift_domain_name>" \
  --from-literal=container_name="<swift_container_name>"

  2. Optional: Provide project-specific data and region if required by your Swift deployment: 

    $ oc -n openshift-logging create secret generic logging-loki-swift \
  --from-literal=auth_url="<swift_auth_url>" \
  --from-literal=username="<swift_username>" \
  --from-literal=user_domain_name="<swift_user_domain_name>" \
  --from-literal=user_domain_id="<swift_user_domain_id>" \
  --from-literal=user_id="<swift_user_id>" \
  --from-literal=password="<swift_password>" \
  --from-literal=domain_id="<swift_domain_id>" \
  --from-literal=domain_name="<swift_domain_name>" \
  --from-literal=container_name="<swift_container_name>" \
  --from-literal=project_id="<swift_project_id>" \
  --from-literal=project_name="<swift_project_name>" \
  --from-literal=project_domain_id="<swift_project_domain_id>" \
  --from-literal=project_domain_name="<swift_project_domain_name>" \
  --from-literal=region="<swift_region>"

Verification

Run the following command to verify that the secret was created successfully: 

$ oc get secret logging-loki-swift -n openshift-logging
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top