Reference: https://github.com/hashicorp/consul/issues/4090
Examples covering a variety of potential use cases. Verified via `sockaddr eval` and `console agent -bind` on a test machine:
```console
# Baseline
$ sockaddr eval 'GetAllInterfaces'
[127.0.0.1/8 {1 65536 lo up|loopback} ::1 {1 65536 lo up|loopback} 10.0.0.10/8 {2 1500 eth0 b8:27:eb:7b:36:95 up|broadcast|multicast} fe80::12dc:5e4d:8ff8:2d96/64 {2 1500 eth0 b8:27:eb:7b:36:95 up|broadcast|multicast} 192.168.1.10/24 {3 1500 wlan0 b8:27:eb:2e:63:c0 up|broadcast|multicast} fe80::b6dc:5758:c306:b15b/64 {3 1500 wlan0 b8:27:eb:2e:63:c0 up|broadcast|multicast}]
# Using address within a specific CIDR
$ sockaddr eval 'GetPrivateInterfaces | include "network" "10.0.0.0/8" | attr "address"'
10.0.0.10
# Using a static network interface name
$ sockaddr eval 'GetInterfaceIP "eth0"'
10.0.0.10
# Using regular expression matching for network interface name that is forwardable and up
$ sockaddr eval 'GetAllInterfaces | include "name" "^eth" | include "flags" "forwardable|up" | attr "address"'
10.0.0.10
```
https://github.com/hashicorp/consul/issues/2121https://www.freedesktop.org/software/systemd/man/systemd.service.html
When set to notify, systemd will not attempt to start any dependent
services until after consul sends the notify signal. This is useful
in cases where there services that rely on the local consul agent
to be up and functional before they can start. The default is simple,
which will immediately mark the service as up and functioning even
if consul has not yet joined the cluster and has started listening
for connnections.
* Updating docs landing page since all the guides have moved
* fixing line wrap
* Giving the docs landing page content with CTAs
* Updated the language for the config and learn boxes
* fixing spacing
* WIP
* Document all the new Envoy L7 configs
* Apply suggestions from code review
Co-Authored-By: banks <banks@banksco.de>
* Rewrite dynamic config and add in TODO links
* Add some config entry docs
* Update website/source/docs/agent/config_entries.html.md
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* Update website/source/docs/agent/config_entries.html.md
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* Get rid of double negative
* Some incremental updates
* Update the config list docs to not point to service-default related things.
* A few more doc updates to get rid of some service-defaults specific linking info in the cli docs
* In progress update
* Update website/source/docs/agent/config_entries.html.md
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* Reword bootstrap section
* Update example proxy-defaults config
* Finish up the examples section for managing config entries with the CLI
* Update website/source/docs/agent/config_entries.html.md
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* Use $ for shell command start
* Make it very clear that the normal way to manage things is via the API/CLI
* Update website/source/docs/agent/options.html.md
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* New guide listing common error messages and what to do about them
* Pasted in updates from StackPad edit
* Update website/source/docs/guides/common-errors.md
Co-Authored-By: tradel <todd@radel.us>
* Update website/source/docs/guides/common-errors.md
Co-Authored-By: tradel <todd@radel.us>
* Update website/source/docs/guides/common-errors.md
Co-Authored-By: tradel <todd@radel.us>
* add subheadings in config file errors, move doc out of guides
* modify guide index to point to learn
* adding to the redirects is a wip, updated the side navigation.
* add tracks to list
* Fixing redirects
* Update website/source/docs/guides/index.html.md
Co-Authored-By: judithpatudith <judith@hashicorp.com>
* Update website/source/docs/guides/index.html.md
Co-Authored-By: judithpatudith <judith@hashicorp.com>
* Update website/source/docs/guides/index.html.md
Co-Authored-By: judithpatudith <judith@hashicorp.com>
* Update website/source/docs/guides/index.html.md
Co-Authored-By: judithpatudith <judith@hashicorp.com>
* finish out track listings
* finishing redirects.
* change advanced language to production, add relationship of guides and docs
* Update website/source/redirects.txt
Co-Authored-By: judithpatudith <judith@hashicorp.com>
* Add api docs for the config entry endpoints
* Add enable_central_service_config field to agent docs
* Add docs for config entry CLI operations
* Fix wording and links in config entry docs
* Add links to the central service config option
* Update the central service config setting description.
Also update some snapshot agent docs
* Enforce correct permissions when registering a check
Previously we had attempted to enforce service:write for a check associated with a service instead of node:write on the agent but due to how we decoded the health check from the request it would never do it properly. This commit fixes that.
* Update website/source/docs/commands/snapshot/agent.html.markdown.erb
Co-Authored-By: mkeeler <mkeeler@users.noreply.github.com>
* starting broken link fixes
* Updating the other links for ACLs
* Updating the rest of the links
* fixing acl required links.
* update a bunch of other links
* updated a couple more broken links based on Alvins checker
* removed the extra s
Fixes: #4222
# Data Filtering
This PR will implement filtering for the following endpoints:
## Supported HTTP Endpoints
- `/agent/checks`
- `/agent/services`
- `/catalog/nodes`
- `/catalog/service/:service`
- `/catalog/connect/:service`
- `/catalog/node/:node`
- `/health/node/:node`
- `/health/checks/:service`
- `/health/service/:service`
- `/health/connect/:service`
- `/health/state/:state`
- `/internal/ui/nodes`
- `/internal/ui/services`
More can be added going forward and any endpoint which is used to list some data is a good candidate.
## Usage
When using the HTTP API a `filter` query parameter can be used to pass a filter expression to Consul. Filter Expressions take the general form of:
```
<selector> == <value>
<selector> != <value>
<value> in <selector>
<value> not in <selector>
<selector> contains <value>
<selector> not contains <value>
<selector> is empty
<selector> is not empty
not <other expression>
<expression 1> and <expression 2>
<expression 1> or <expression 2>
```
Normal boolean logic and precedence is supported. All of the actual filtering and evaluation logic is coming from the [go-bexpr](https://github.com/hashicorp/go-bexpr) library
## Other changes
Adding the `Internal.ServiceDump` RPC endpoint. This will allow the UI to filter services better.
* [docs] security warning about Helm chart
Correct security warning about helm chart to caution about default Consul install.
* clarify that k8s or consul should be secure
* website: specify value of acquire/release params for kv
* website: clarify leader election usage in TTL docs
* website: document minimal value of lockdelay
I believe it uses the default when parsing 0 as it
views that as an empty parameter in this case.
- the space after `=` is significant in sc parameters (binPath= "<path> <args>, start= auto)
- given the text "the service automatically starts up during/after boot", added `start= auto` to
the example, otherwise the service will be set to Manual start mode.
* Added a note to GCE auto-join credentials option
Simply added a note to remind users that putting a json file in the config-dir will make consul parse it as a config file.
Hope to help someone else avoid wasting a day because of these errors:
==> Error parsing /etc/consul.d/credentials.json: 10 error(s) occurred: * invalid config key private_key
* Updated according to style guidelines
Co-Authored-By: delamart <erik@delamarter.ch>
* Docs: Remove default_policy From Code Example
It is not needed according to:
https://www.consul.io/docs/agent/acl-system.html#configuring-acls
* Docs: Cleanup Commands And Their Output On ACL Guide Page
Remove extra spaces and newlines
Ensure rules match input rules
* Docs: Remove Incomplete "Added In Version" Statement
Version added is specified on parent option
* Docs: Fix Broken Links
* Docs: Minor Sentence Tweaks
This PR introduces reloading tls configuration. Consul will now be able to reload the TLS configuration which previously required a restart. It is not yet possible to turn TLS ON or OFF with these changes. Only when TLS is already turned on, the configuration can be reloaded. Most importantly the certificates and CAs.
* Fix race condition in DNS when using cache
The healty node filtering was modifying the result from the cache, which
caused a crash when multiple queries were made to the same service
simultaneously.
We now copy the node slice before filtering to ensure we do not modify
the data stored in the cache.
* Fix wording in dns cache config doc
s/dns_max_age/cache_max_age/
This PR adds two features which will be useful for operators when ACLs are in use.
1. Tokens set in configuration files are now reloadable.
2. If `acl.enable_token_persistence` is set to `true` in the configuration, tokens set via the `v1/agent/token` endpoint are now persisted to disk and loaded when the agent starts (or during configuration reload)
Note that token persistence is opt-in so our users who do not want tokens on the local disk will see no change.
Some other secondary changes:
* Refactored a bunch of places where the replication token is retrieved from the token store. This token isn't just for replicating ACLs and now it is named accordingly.
* Allowed better paths in the `v1/agent/token/` API. Instead of paths like: `v1/agent/token/acl_replication_token` the path can now be just `v1/agent/token/replication`. The old paths remain to be valid.
* Added a couple new API functions to set tokens via the new paths. Deprecated the old ones and pointed to the new names. The names are also generally better and don't imply that what you are setting is for ACLs but rather are setting ACL tokens. There is a minor semantic difference there especially for the replication token as again, its no longer used only for ACL token/policy replication. The new functions will detect 404s and fallback to using the older token paths when talking to pre-1.4.3 agents.
* Docs updated to reflect the API additions and to show using the new endpoints.
* Updated the ACL CLI set-agent-tokens command to use the non-deprecated APIs.
Adds two new configuration parameters "dns_config.use_cache" and
"dns_config.cache_max_age" controlling how DNS requests use the agent
cache when querying servers.
* Add common blocking implementation details to docs
These come up over and over again with blocking query loops in our own code and third-party's. #5333 is possibly a case (unconfirmed) where "badly behaved" blocking clients cause issues, however since we've never explicitly documented these things it's not reasonable for third-party clients to have guessed that they are needed!
This hopefully gives us something to point to for the future.
It's a little wordy - happy to consider breaking some of the blocking stuff out of this page if we think it's appropriate but just wanted to quickly plaster over this gap in our docs for now.
* Update index.html.md
* Apply suggestions from code review
Co-Authored-By: banks <banks@banksco.de>
* Update index.html.md
* Update index.html.md
* Clearified monotonically
* Fixing formating
* Updating the Helm chart to include ACL parameter and examples.
* Updates based on feedback.
* Update website/source/docs/platform/k8s/helm.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Confirm RA against Consul 1.3
Change product_version frontmatter to ea_version and increase to 1.3
* Confirm DG against Consul 1.3
Change product_version frontmatter to ea_version and increase to 1.3
The guide currently uses node, service, and service for the UI Policy.
This will cause a practically useless UI. This patch uses the _prefix
variants instead which will have the intended behavior.
It appears that the `read` command for ACL policies was used to template the `read` command for ACL tokens, and an invalid option was not dropped from the docs.
Given a query like:
```
{
"Name": "tagged-connect-query",
"Service": {
"Service": "foo",
"Tags": ["tag"],
"Connect": true
}
}
```
And a Consul configuration like:
```
{
"services": [
"name": "foo",
"port": 8080,
"connect": { "sidecar_service": {} },
"tags": ["tag"]
]
}
```
If you executed the query it would always turn up with 0 results. This was because the sidecar service was being created without any tags. You could instead make your config look like:
```
{
"services": [
"name": "foo",
"port": 8080,
"connect": { "sidecar_service": {
"tags": ["tag"]
} },
"tags": ["tag"]
]
}
```
However that is a bit redundant for most cases. This PR ensures that the tags and service meta of the parent service get copied to the sidecar service. If there are any tags or service meta set in the sidecar service definition then this copying does not take place. After the changes, the query will now return the expected results.
A second change was made to prepared queries in this PR which is to allow filtering on ServiceMeta just like we allow for filtering on NodeMeta.
* Support rate limiting and concurrency limiting CSR requests on servers; handle CA rotations gracefully with jitter and backoff-on-rate-limit in client
* Add CSR rate limiting docs
* Fix config naming and add tests for new CA configs
* Stared updaing links for the learn migration
* Language change cluster -> datacenter (#5212)
* Updating the language from cluster to datacenter in the backup guide to be consistent and more accurate.
* missed some clusters
* updated three broken links for the sidebar nav
Adds info about `k8stag` and `nodePortSyncType` options that were
added in consul-helm v0.5.0.
Additionally moves the k8sprefix to match the order in the Helm chart
values file, while also clarifying that it only affects one sync
direction.
If a user installs the default Helm chart Consul on a Kubernetes
cluster that is open to the internet, it is lacking some important
security configurations.
* Re-worked the ACL guide into two docs and an updated guide.
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Updating syntax based on amayer5125's comments.
* Missed one of amayer5125's comments
* found a bad link in the acl system docs
* fixing a link in the rules docs
This endpoint aggregates all checks related to <service id> on the agent
and return an appropriate http code + the string describing the worst
check.
This allows to cleanly expose service status to other component, hiding
complexity of multiple checks.
This is especially useful to use consul to feed a load balancer which
would delegate health checking to consul agent.
Exposing this endpoint on the agent is necessary to avoid a hit on
consul servers and avoid decreasing resiliency (this endpoint will work
even if there is no consul leader in the cluster).
* Adding the new backup guide
* Update website/source/docs/guides/backup.html.md
Looks good.
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/backup.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/backup.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/backup.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Updated the directions for the restore command.
* Update website/source/docs/guides/backup.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/backup.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* updated the token env
* Trying to make it extra clear where to run the commands.
* added not that list of backed up items isn't inclusive
There has been some confusion about the formating of multi-line
string variables in the Helm chart. This adds examples for these
situations, hopefully clarifying things for users.
* added a new section for adding servers, updated section titles, and added code snippets.
* Fixing typos
* fixing typos
* Addressing some of Paul's feedback.
* Updated the outage recovery recommendation
* Adding examples and a summary. Minor structure updates.
* Added a link to the deployment guide, but needed to remove a sentence referring to a guide that's not published yet.
* fixed typo
This changes with time so will opt to not hardcoding this. Investigated using the middleman helper to render
out the current configured version but that won't exist on learn.hashicorp.com so I think this
is the most future-proof way.
* Adding the new Consul Template Guide.
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Making updates based on Pauls feedback.
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/guides/consul-template.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Couple more updates based on Pauls feedback.
* updated the intro to include how template can replace api use
* updated the address
* Adding minikube guide to the index page.
* Adds images for Minikube guide
* Adds notes about Helm YAML configuration
* Embed Wistia video for Consul Minikube guide
* Cleans up menus, instructions, Helm steps
* Adds captions for all images
* Uses Docker images hosted on hashicorp org for demo
* Adds link to Minikube guide from menu and k8s index page
* Clarify steps in Minikube/Kubernetes guide
* Adds note about use of Fastly VCL for redirects
Some redirects are not possible with a redirect file, so we send traffic to
learn.hashicorp.com with custom VCL (Varnish) handlers using the Fastly web
admin.
Future migrations of content to learn.hashicorp.com should also use this
approach.
* adding file2consul listing
* minor edit
* modified wording added some punctuation
* Moved file2consul so it is listed in alpha order. Replaces Pull Request # #4942
* website: add multi-dc enterprise landing page
* website: switch all 1.4.0 alerts/RC warnings
* website: connect product wording
Co-Authored-By: pearkes <jackpearkes@gmail.com>
* website: remove RC notification
* commmand/acl: fix usage docs for ACL tokens
* agent: remove comment, OperatorRead
* website: improve multi-dc docs
Still not happy with this but tried to make it slightly more informative.
* website: put back acl guide warning for 1.4.0
* website: simplify multi-dc page and respond to feedback
* Fix Multi-DC typos on connect index page.
* Improve Multi-DC overview.
A full guide is a WIP and will be added post-release.
* Fixes typo avaiable > available
There is a fine line between making the helm chart easy and simple to
use and supporting lots of configurability. This documents options for
users who would like to extend the Helm chart beyond what is readily
available in the `values.yaml` file.
This adds two Helm chart values into the documentation with details
that have come up in several issues.
Additionally, it notes that persistent volumes and their claims need
to be removed manually because of current kubernetes and helm design.
* Adds redirects for Getting Started pages
* Uses correct links to resources at learn.hashicorp
* Reconfigures "Learn more" links to point to learn.hashicorp
* Links to learn.hashicorp on segmentation page
* Adds redirect for sample config file
* Fixes links to Getting Started guide on learn.hashicorp
* Remove getting started guide which is now on learn.hashicorp
* Corrects link to `consul/io` which should go to `consul.io`
* Revert "Remove getting started guide which is now on learn.hashicorp"
This reverts commit 2cebacf402f83fb936718b41ac9a27415f4e9f21 so a placeholder
message can be written here while we are transitioning content to
learn.hashicorp
* Adding a new page for getting started to direct users to learn.
* Added a note at the being of each doc to notify users about the temporary repo change.
* Revert "Added a note at the being of each doc to notify users about the temporary repo change."
This reverts commit 9a2a8781f9705028e4f53f758ef235e74b2b7198.
From conversation at https://github.com/hashicorp/consul/pull/4878
* Removes redirect from sample web.json demo file
* Removed typo
* Update the ACL API docs
* Add a CreateTime to the anon token
Also require acl:read permissions at least to perform rule translation. Don’t want someone DoSing the system with an open endpoint that actually does a bit of work.
* Fix one place where I was referring to id instead of AccessorID
* Add godocs for the API package additions.
* Minor updates: removed some extra commas and updated the acl intro paragraph
* minor tweaks
* Updated the language to be clearer
* Updated the language to be clearer for policy page
* I was also confused by that! Your updates are much clearer.
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Sounds much better.
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Updated sidebar layout and deprecated warning
* Fix partial rendering in service command (CLI) help
* Fix sample JSON to be a valid json for service registration
* Add missing id field to make the complete document complete.
This field was added back into the helm chart, but it was not added
back to the documentation. This adds it, then additionally fixes a
few typos in the same file.
* Implement CLI token cloning & special ID handling
* Update a couple CLI commands to take some alternative options.
* Document the CLI.
* Update the policy list and set-agent-token synopsis
Based on info from consul-helm issue 16, the formatting of the helm
chart value for joining an external cluster needs to be specified
as a yaml array. This updates the documentation to reflect this.
This PR is almost a complete rewrite of the ACL system within Consul. It brings the features more in line with other HashiCorp products. Obviously there is quite a bit left to do here but most of it is related docs, testing and finishing the last few commands in the CLI. I will update the PR description and check off the todos as I finish them over the next few days/week.
Description
At a high level this PR is mainly to split ACL tokens from Policies and to split the concepts of Authorization from Identities. A lot of this PR is mostly just to support CRUD operations on ACLTokens and ACLPolicies. These in and of themselves are not particularly interesting. The bigger conceptual changes are in how tokens get resolved, how backwards compatibility is handled and the separation of policy from identity which could lead the way to allowing for alternative identity providers.
On the surface and with a new cluster the ACL system will look very similar to that of Nomads. Both have tokens and policies. Both have local tokens. The ACL management APIs for both are very similar. I even ripped off Nomad's ACL bootstrap resetting procedure. There are a few key differences though.
Nomad requires token and policy replication where Consul only requires policy replication with token replication being opt-in. In Consul local tokens only work with token replication being enabled though.
All policies in Nomad are globally applicable. In Consul all policies are stored and replicated globally but can be scoped to a subset of the datacenters. This allows for more granular access management.
Unlike Nomad, Consul has legacy baggage in the form of the original ACL system. The ramifications of this are:
A server running the new system must still support other clients using the legacy system.
A client running the new system must be able to use the legacy RPCs when the servers in its datacenter are running the legacy system.
The primary ACL DC's servers running in legacy mode needs to be a gate that keeps everything else in the entire multi-DC cluster running in legacy mode.
So not only does this PR implement the new ACL system but has a legacy mode built in for when the cluster isn't ready for new ACLs. Also detecting that new ACLs can be used is automatic and requires no configuration on the part of administrators. This process is detailed more in the "Transitioning from Legacy to New ACL Mode" section below.
* agent/debug: add package for debugging, host info
* api: add v1/agent/host endpoint
* agent: add v1/agent/host endpoint
* command/debug: implementation of static capture
* command/debug: tests and only configured targets
* agent/debug: add basic test for host metrics
* command/debug: add methods for dynamic data capture
* api: add debug/pprof endpoints
* command/debug: add pprof
* command/debug: timing, wg, logs to disk
* vendor: add gopsutil/disk
* command/debug: add a usage section
* website: add docs for consul debug
* agent/host: require operator:read
* api/host: improve docs and no retry timing
* command/debug: fail on extra arguments
* command/debug: fixup file permissions to 0644
* command/debug: remove server flags
* command/debug: improve clarity of usage section
* api/debug: add Trace for profiling, fix profile
* command/debug: capture profile and trace at the same time
* command/debug: add index document
* command/debug: use "clusters" in place of members
* command/debug: remove address in output
* command/debug: improve comment on metrics sleep
* command/debug: clarify usage
* agent: always register pprof handlers and protect
This will allow us to avoid a restart of a target agent
for profiling by always registering the pprof handlers.
Given this is a potentially sensitive path, it is protected
with an operator:read ACL and enable debug being
set to true on the target agent. enable_debug still requires
a restart.
If ACLs are disabled, enable_debug is sufficient.
* command/debug: use trace.out instead of .prof
More in line with golang docs.
* agent: fix comment wording
* agent: wrap table driven tests in t.run()