Skip to content

Conversation

@pgarciaq
Copy link
Contributor

Fix development environment when using Docker on Linux. Probably applicable to any from-scratch development environment, even Mac.

Jira Ticket

No Jira ticket, just a very stubborn product manager on a weekend.

Description

When following the "Developing with Docker" instructions on Fedora Linux 43, "make load-customer-test-data" fails with 404's because nise cannot reach MinIO.

This PR includes 3 fixes:

  1. Update the S3_ENDPOINT to the MinIO URL
  2. Add an environment section to docker-compose.yml
  3. Use mc alias instead of deprecated commands

Testing

  1. Checkout Branch on a new Linux machine, with no Koku development environment, container images, etc. Make sure there's nothing preexisting.
  2. Follow README.md to develop with Docker: make docker-up, make create-test-customer, make load-test-customer-data
  3. Without this PR, make load-test-customer-data will fail with 404, MinIO buckets will not be created and data will not be loaded at all. With this PR, buckets are created and data is loaded.

Release Notes

  • Fix Docker development environment on Linux

…load-customer-test-data from reaching MinIO

- Update minio client commands to newer mc versions
@pgarciaq pgarciaq requested review from a team as code owners December 14, 2025 18:22
@gemini-code-assist
Copy link

Summary of Changes

Hello @pgarciaq, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical issue preventing the Docker development environment from functioning correctly on Linux, specifically when nise attempts to interact with MinIO. The changes ensure that MinIO is properly accessible and configured within the Docker setup, resolving 404 errors encountered during test data loading and enabling a smooth development workflow.

Highlights

  • MinIO Endpoint Correction: The S3_ENDPOINT in .env.example has been updated from "http://localhost:9000" to "http://koku-minio:9000" to correctly reference the MinIO service within the Docker network, resolving connectivity issues.
  • Docker Compose Environment Variables: The docker-compose.yml file now explicitly defines MINIO_ENDPOINT, S3_ACCESS_KEY, and S3_SECRET within the environment section of the mc service, ensuring these variables are correctly passed for MinIO client operations.
  • MinIO Client Command Modernization: Deprecated mc config host add commands in docker-compose.yml have been replaced with mc alias set, and mc rb --force commands now include || true for robustness, preventing script failures if buckets do not exist.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution.

Copy link

@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request fixes the Docker development environment on Linux by updating the S3 endpoint configuration and modernizing the MinIO client commands. The changes are correct and improve the robustness of the local setup. I've added one suggestion to refactor the bucket creation script in docker-compose.yml to make it more concise and maintainable by using a loop.

Comment on lines +664 to 672
/usr/bin/mc rb --force local/koku-bucket/ || true;
/usr/bin/mc mb --quiet local/koku-bucket/;
/usr/bin/mc anonymous set public local/koku-bucket;
/usr/bin/mc rb --force local/ocp-ingress/;
/usr/bin/mc rb --force local/ocp-ingress/ || true;
/usr/bin/mc mb --quiet local/ocp-ingress/;
/usr/bin/mc anonymous set public local/ocp-ingress;
/usr/bin/mc rb --force local/metastore/;
/usr/bin/mc rb --force local/metastore/ || true;
/usr/bin/mc mb --quiet local/metastore/;
/usr/bin/mc anonymous set public local/metastore;

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The commands for creating buckets are repeated three times. You can use a for loop to make this script more concise and easier to maintain. This avoids repetition and makes it clearer which buckets are being created.

      for bucket in koku-bucket ocp-ingress metastore; do
        /usr/bin/mc rb --force "local/$bucket/" || true;
        /usr/bin/mc mb --quiet "local/$bucket/";
        /usr/bin/mc anonymous set public "local/$bucket";
      done;

@pgarciaq
Copy link
Contributor Author

As a curiosity, it was Cursor the one that found the root cause and provided the fix. Here's the report it wrote.

MinIO Bucket Creation Debugging Guide

Problem

When running make create-test-customer followed by make load-test-customer-data, the process fails because the required S3 buckets are not created in MinIO. The error typically shows:

404 File upload failed.

or similar errors indicating that the bucket doesn't exist.

Where Buckets Are Created

The buckets are created by the create-parquet-bucket container defined in docker-compose.yml.

Location: docker-compose.yml lines 652-669

Container: create-parquet-bucket (uses MinIO client mc to create buckets)

Buckets Created:

  • koku-bucket - Main S3 bucket (default value of S3_BUCKET_NAME)
  • ocp-ingress - For OCP payload uploads
  • metastore - For Trino/Hive metastore

Root Cause

The create-parquet-bucket container fails to create buckets because:

  1. Missing Environment Variables: The container doesn't receive the required environment variables (MINIO_ENDPOINT, S3_ACCESS_KEY, S3_SECRET) because the docker-compose.yml configuration doesn't include an environment: section for this service.

  2. Outdated Command Syntax: The container uses the old mc config host command instead of the newer mc alias command.

  3. Connection Failure: Without the environment variables, the container tries to connect to localhost:9000 instead of koku-minio:9000, causing connection refused errors.

Error Logs

When the container fails, you'll see errors like:

mc: <ERROR> `config` is not a recognized command.
mc: <ERROR> Unable to validate target `local/koku-bucket/`. Get "http://localhost:9000/koku-bucket/?location=": dial tcp [::1]:9000: connect: connection refused

Solution

Option 1: Quick Fix - Manually Create Buckets

If you need the buckets immediately, you can create them manually:

# Set up MinIO alias
docker exec koku-minio mc alias set local http://localhost:9000 kokuminioaccess kokuminiosecret --api s3v4

# Create buckets
docker exec koku-minio mc mb local/koku-bucket
docker exec koku-minio mc mb local/ocp-ingress
docker exec koku-minio mc mb local/metastore

# Set public access permissions
docker exec koku-minio mc anonymous set public local/koku-bucket
docker exec koku-minio mc anonymous set public local/ocp-ingress
docker exec koku-minio mc anonymous set public local/metastore

Option 2: Permanent Fix - Update docker-compose.yml

The create-parquet-bucket service in docker-compose.yml should be updated to include environment variables:

create-parquet-bucket:
  image: minio/mc:latest
  depends_on:
    - minio
  environment:
    - MINIO_ENDPOINT=${MINIO_ENDPOINT-http://koku-minio:9000}
    - S3_ACCESS_KEY=${S3_ACCESS_KEY-kokuminioaccess}
    - S3_SECRET=${S3_SECRET-kokuminiosecret}
  entrypoint: >
    /bin/sh -c "
    /usr/bin/mc alias rm local || true;
    /usr/bin/mc alias set local $MINIO_ENDPOINT $S3_ACCESS_KEY $S3_SECRET --api s3v4;
    /usr/bin/mc rb --force local/koku-bucket/ || true;
    /usr/bin/mc mb --quiet local/koku-bucket/;
    /usr/bin/mc anonymous set public local/koku-bucket;
    /usr/bin/mc rb --force local/ocp-ingress/ || true;
    /usr/bin/mc mb --quiet local/ocp-ingress/;
    /usr/bin/mc anonymous set public local/ocp-ingress;
    /usr/bin/mc rb --force local/metastore/ || true;
    /usr/bin/mc mb --quiet local/metastore/;
    /usr/bin/mc anonymous set public local/metastore;
    "

Key Changes:

  1. Added environment: section with required variables
  2. Changed mc config host to mc alias
  3. Added || true to prevent failures if buckets already exist

Debugging

Check Container Status

docker ps -a --filter "name=create-parquet" --format "table {{.Names}}\t{{.Status}}"

View Container Logs

docker logs koku-create-parquet-bucket-1

Check if Buckets Exist

docker exec koku-minio mc alias set local http://localhost:9000 kokuminioaccess kokuminiosecret --api s3v4
docker exec koku-minio mc ls local/

Use Debug Script

A debug script is available at dev/scripts/debug_minio_buckets.sh:

./dev/scripts/debug_minio_buckets.sh

This script will:

  • Check if MinIO is running
  • Verify MinIO accessibility
  • Display environment variables
  • List existing buckets
  • Show container status and logs
  • Provide solutions

Environment Variables

The following environment variables are used:

Variable Default Value Description
S3_BUCKET_NAME koku-bucket Main S3 bucket name
MINIO_ENDPOINT http://koku-minio:9000 MinIO server endpoint
S3_ACCESS_KEY kokuminioaccess MinIO access key
S3_SECRET kokuminiosecret MinIO secret key
S3_BUCKET_NAME_OCP_INGRESS ocp-ingress OCP ingress bucket name

Verification

After creating buckets, verify they exist:

docker exec koku-minio mc ls local/

You should see:

[DATE]     0B koku-bucket/
[DATE]     0B metastore/
[DATE]     0B ocp-ingress/

Related Files

  • docker-compose.yml - Container definitions
  • dev/scripts/debug_minio_buckets.sh - Debug script
  • dev/scripts/load_test_customer_data.sh - Script that uses the buckets
  • koku/koku/settings.py - S3 configuration settings

Additional Notes

  • The create-parquet-bucket container is a one-time initialization container that should run successfully when Docker Compose starts
  • If the container fails, subsequent containers that depend on it (like hive-metastore) may also fail
  • The buckets need to exist before running make load-test-customer-data
  • Buckets are persistent and stored in ./dev/containers/minio/ directory

Troubleshooting Checklist

  • MinIO container is running (docker ps | grep koku-minio)
  • MinIO is accessible (curl http://localhost:9000/minio/health/live)
  • create-parquet-bucket container has environment variables
  • Container logs show successful bucket creation
  • Buckets exist in MinIO (mc ls local/)
  • Buckets have public access permissions
  • S3_BUCKET_NAME environment variable matches the bucket name

@codecov
Copy link

codecov bot commented Dec 14, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.3%. Comparing base (92387c2) to head (90cd7c1).

Additional details and impacted files
@@          Coverage Diff          @@
##            main   #5832   +/-   ##
=====================================
  Coverage   94.3%   94.3%           
=====================================
  Files        345     345           
  Lines      29768   29768           
  Branches    3254    3254           
=====================================
+ Hits       28073   28074    +1     
+ Misses      1101    1100    -1     
  Partials     594     594           
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant