docker-library / docker-library/docs

Document issues with postgresql, K8s, and transparent huge pages

Open
#2,355 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Shell
Stars
5.3k
Forks
2.2k
Avg merge
1d 18h
Merged PRs (30d)
11

Description

PostgreSQL, K8s, and transparent huge pages do not play nice together; there are several open issues discussing the exact details here;

https://github.com/docker-library/postgres/issues/946

https://github.com/docker-library/postgres/issues/451#issuecomment-447472044

It took me a very long time to figure out the workarounds that I've documented (mostly for my own sake) in https://github.com/jdevries3133/homelab_cluster/tree/main/postgres_hello_world.

I realize there are some docs about how to configure PostgreSQL in general (https://github.com/docker-library/docs/tree/master/postgres#database-configuration). I think it would be good to add a sub-section about this problem. As I understand it (and I think I may be wrong, to some extent), the problem is:

  • containerd (and maybe other container runtimes) are unable to provide hugepages to containers
  • nonetheless, PostgreSQL is configured to "try" to use transparent hugepages
  • although transparent hugepages cannot really be provided, in this context, postgres somehow internally comes to believe that it has access to transparent hugepages
  • ???
  • segmentation fault

And, therefore, the solution I have come to is (maybe) to disable transparent hugepages on the underlying K8s nodes and to also to disable transparent hugepages in PostgreSQL configuration.

To conclude: I have some ubuntu server nodes. I do some kubeadm cluseter. I try to use PostgreSQL. PostgreSQL no work. Seems like this is a typical enough pattern we should try to make it stink less if possible!

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The relevant entry point is the PostgreSQL documentation under postgres#database-configuration; review the linked docker-library/postgres issues and the reported homelab_cluster/postgres_hello_world workaround first. Confirm which PostgreSQL, Kubernetes, container-runtime, and node settings are accurate, then add a focused subsection describing the failure and workaround. Done means the guidance is technically verified and integrated into the existing database-configuration docs.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes, postgresql, ubuntu
Domain
databases, documentation, infrastructure, operating-systems
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.