Expose the CLI reference pages a bit better from the index #1966
Conversation
|
|
||
| Specify the api version the client should report. If you get an error about | ||
| `client and server don't have same version` you may use this environment | ||
| variable to have the client report a version compatible with the server. |
There was a problem hiding this comment.
We should make it clear that this is not really safe or "supported".
There was a problem hiding this comment.
I wasn't sure how to word it. I was initially thinking of something like "Setting an api version may cause some features to fail, and is not officially supported."
There was a problem hiding this comment.
We had some discussion on this in docker; moby/moby#15964 (comment)
It's not yet merged, but it will be described as a "power user" feature, and "use at your own risk"
There was a problem hiding this comment.
This is a bit ambiguous so more words clarify a bit (or a lot):
The Docker command line client supports a specific version of the Docker API. If you receive a client and server don't have same version error using the command line, setting this environment variable prevents this error. Set it to the version you want the client to report, which is typically a version compatible with the server.
There was a problem hiding this comment.
Hmm, the intent has changed a bit with this wording and now it's not really correct, how about:
The Docker API only supports requests from clients which report a specific version. If you receive a
client and server don't have same versionerror usingdocker-compose, setting this environment variable prevents this error. Set it to the version you want the client to report. typically the server version.NOTE: Setting a different API version will prevent some features from working, and is not officially supported.
There was a problem hiding this comment.
Is it the specific version or a "matching" version? I think from your rewrite (noice!) same is true. So lets say matching.
"report. typically" -> "report, typically"
Then I got to your note and hit a wall. Why are we suggesting they do this if we don't support it? Which features do I lose if I do do it. Why wouldn't I just fix the problem with the client/API mismatch ---> if this was in the discussion...let me know. We kind of need to summarize the answers here to make the doc useful.
There was a problem hiding this comment.
"matching" sounds good.
Which features do I lose if I do do it.
That will depend on the version of the client and the server. It will be different for basically every combination, so we can't accurately enumerate them here.
Why wouldn't I just fix the problem with the client/API mismatch
Sometimes (especially at larger orgs, or when there are shared hosts where the users don't necessarily have root) it takes a lot longer to upgrade the server. The server might only be upgraded every second or third version, where as a developer can easily upgrade the client (docker-compose) at any time.
So this environment variable is a workaround for when you want bug fixes or new features from the client, but you can't get a newer server just yet.
There was a problem hiding this comment.
@dnephin thanks for the answers. Let's try something like what you see below. It explains the situation much more completely and gives them a way to troubleshoot problems (assuming I got it right.) Also, I think we should notify Docker Support about this setting --- have y'all talked to them about it?
------>
The Docker API only supports requests from clients which report a specific version. If you receive a client and server don't have same version error using docker-compose, you can workaround this error by setting this environment variable. Set the version value to match the server version.
Setting this variable is intended as a workaround for situations where you need to run temporarily with a mismatch between the client and server version. For example, if you can upgrade the client but need to wait to upgrade the server.
Running with this variable set and a known mismatch does prevent some Docker features from working properly. The exact features that fail would depend on the Docker client and server versions. For this reason, running with this variable set is only intended as a workaround and it is not officially supported.
If you run into problems running with this set, resolve the mismatch through upgrade and remove this setting to see if your problems resolve before notifying support.
There was a problem hiding this comment.
I think we should notify Docker Support about this setting
I agree, what's the right way to communicate this type of thing with support?
That rewording sounds great! Thanks!
|
Seems like a good idea to me. (ping @moxiegirl) Not strictly related to your changes, but I find the distinction between Furthermore, the Compose command's environment variables are documented on a page called "Introduction to the CLI", whereas the page called "Compose environment variables reference" documents the environment variables that populate linked containers (which we expressly tell people not to use). |
|
I completely agree with both of those points, but I didn't want to make too many changes up-front. |
|
@aanand The
It also allows for this kind of reference: Happy to explain more if that isn't clear. |
Nice, I've wanted this! @moxiegirl what do you think about the doc changes in this PR ? |
Signed-off-by: Daniel Nephin <dnephin@docker.com>
Signed-off-by: Daniel Nephin <dnephin@gmail.com>
Signed-off-by: Daniel Nephin <dnephin@gmail.com>
dnephin
force-pushed
the
docs_update
branch
from
c7e54f3 to
1eb925e
Compare
|
Wording for the |
|
LGTM |
Expose the CLI reference pages a bit better from the index
I noticed while reading over our docs that it was really hard for me to find the environment variables and command reference. I think this change will make the situation better by cross-linking the reference pages to each other, and by adding a "where to go next" section to the overview page.
Also adds docs for a missing cli environment variable.