Vault: Documentation on ha_backend please

[gtmtech]

This page:

https://www.vaultproject.io/docs/config/

Helpfully says the following:

ha_backend (optional) - Configures the storage backend where Vault HA coordination will take place. Must be an HA-supporting backend using the configuration options as documented below. If not set, HA will be attempted on the backend given in the backend parameter.

which is nice, but nowhere else is ha_backend referred to. How is it configured? What are the "configuration options as documented below". Is there an example anywhere?

Is it supposed to be set to exactly the same information as backend? In which case, why on earth is backend required at all?

[vishalnayak]

@gtmtech

How is it configured?

ha_backend "consul" {
  option = value
}

What are the "configuration options as documented below".

Look for "High Availability Options".

Is it supposed to be set to exactly the same information as backend? In which case, why on earth is backend required at all?

backend is for storage, ha_backend is for managing the data store lock to enable high availability mode.

[jefferai]

It's the opposite, you must have backend, but ha_backend can be used if you want ha but your normal backend doesn't support it.

[gtmtech]

Surprised you closed this @vishalnayak - nothing is clear in the docs - I think I've raised a legitimate issue about the fact the docs are unclear and un-understandable without resorting to raising an issue on github.

Do you need a ha_backend section as well to enable HA using something like consul which itself implicitly supports HA? They seem to indicate no, but then why have ha_backend?

Look for "High Availability Options"

• this says>

High Availability Options

All HA backends support the following options. These are discussed in much more detail in the High Availability concepts page.

Is it talking about backends, or ha_backends configuration blocks? The language is interchangable so could be talking about anything

redirect_addr, cluster_addr and disable_clustering should go in a backend section or a ha_backend section?

The whole thing is unclear, and so I have to ask a question on an issue. But close the issue if you like, and people like me will just remain confused 👎

[jefferai]

Do you need a ha_backend section as well to enable HA using something like consul which itself implicitly supports HA? They seem to indicate no, but then why have ha_backend?

I think I addressed this question in my last comment?

[gtmtech]

@jefferai - your recent comment: "ha_backend can be used if you want ha but your normal backend doesn't support it"

Current documentation for ha_backend: "Must be an HA-supporting backend"

(saying opposite things?)

(although your statement makes more sense than the online docs, which make no sense at all :-/ )

[vishalnayak]

@gtmtech The website docs recently went through an overhaul and should eliminate the confusion you are having.

Do you need a ha_backend section as well to enable HA using something like consul which itself implicitly supports HA? They seem to indicate no, but then why have ha_backend?

The doc on the ha_backend block If not set, HA will be attempted on the backend given in the "backend" parameter. is indicative that ha_backend is not a required block. And it is implicit (although, it could have been made explicit, which the new doc structure sort of already does) that the options belonging to HA can go into backend block.

We'd appreciate if you can take a look at the website source and see if those help reduce your confusion. Also, note that backend is being renamed to storage and ha_backend is being renamed to ha_storage (with BC). The new doc structure should go live along with 0.7.0 (soon).

FWIW, I'm reopening this and making a few changes hoping that the concern is addressed. LMK, if it does the job well for you. https://github.com/hashicorp/vault/pull/2471