incomplete API Reference

[jampy]

The API reference for ObjectStoreSpec as of v0.9.0 describes the rather important configuration field, but instead of referencing a clear description for that field references to the matching some Go struct, which is much harder to read - especially for people not familiar with Go.

Since this is a required part of the configuration, I guess it would be very helpful to have a clear description for this field, like the rest of the API reference.

[dosubot]

Hi @jampy! I'm Dosu and I’m helping the plugin-barman-cloud team.

You're right—the API reference for the configuration field in ObjectStoreSpec only links to the Go struct, which isn't very user-friendly. However, the latest documentation now provides a much clearer, human-readable breakdown of what goes into this field, including examples and explanations for each part of the configuration.

The .spec.configuration section lets you define authentication (like S3 credentials), the bucket location (destinationPath), endpoint settings, and advanced options for WAL archiving and base backup (under .spec.configuration.wal and .spec.configuration.data). Retention policies are also set here. For example, a typical configuration might look like:

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: my-store
spec:
  configuration:
    destinationPath: s3://my-bucket/backups/
    endpointURL: https://s3.amazonaws.com
    s3Credentials:
      accessKeyId:
        name: my-secret
        key: ACCESS_KEY_ID
      secretAccessKey:
        name: my-secret
        key: ACCESS_SECRET_KEY
    wal:
      compression: gzip
      maxParallel: 2
    data:
      compression: gzip
      immediateCheckpoint: true
      jobs: 2
  retentionPolicy: "7d"

The new docs explain each field and provide more examples, including how to use features like IRSA (inheritFromIAMRole: true under s3Credentials) and how to avoid pitfalls with fields like serverName (which should be left empty in the ObjectStore resource) see here and here.

Recent documentation updates have added detailed guides and concepts for the plugin, making it much easier to understand and configure the configuration field without needing to read Go code (PR #644, PR #626). If you want a field-by-field breakdown, the main CloudNativePG API docs also provide a table of all possible fields and their descriptions see this table.

If you have a specific scenario or provider in mind, let me know and I can point you to the most relevant example or snippet!

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[malcolmlett-iopex]

I'd like to add one particular point:

• please add objectstore.spec.configuration.s3Credenitals.inheritFromIAMRole=true to the docs here: https://cloudnative-pg.io/plugin-barman-cloud/docs/next/object_stores/

I've spent hours trying to troubleshoot why IRSA was resulting in the following error. I only finally found the solution after stumbling upon the AI-generated notes in the comment above here.

{"level":"error","msg":"while setting backup cloud credentials","logging_pod":"pg1-1","error":"missing Azure credentials",...}