docker-library / docker-library/docs
Document issues with postgresql, K8s, and transparent huge pages
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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