This is like a Möbius strip of code due to the fact that low-level components (serf/memberlist) are connected to high-level components (the catalog and mesh-gateways) in a twisty maze of references which make it hard to dive into. With that in mind here's a high level summary of what you'll find in the patch:
There are several distinct chunks of code that are affected:
* new flags and config options for the server
* retry join WAN is slightly different
* retry join code is shared to discover primary mesh gateways from secondary datacenters
* because retry join logic runs in the *agent* and the results of that
operation for primary mesh gateways are needed in the *server* there are
some methods like `RefreshPrimaryGatewayFallbackAddresses` that must occur
at multiple layers of abstraction just to pass the data down to the right
layer.
* new cache type `FederationStateListMeshGatewaysName` for use in `proxycfg/xds` layers
* the function signature for RPC dialing picked up a new required field (the
node name of the destination)
* several new RPCs for manipulating a FederationState object:
`FederationState:{Apply,Get,List,ListMeshGateways}`
* 3 read-only internal APIs for debugging use to invoke those RPCs from curl
* raft and fsm changes to persist these FederationStates
* replication for FederationStates as they are canonically stored in the
Primary and replicated to the Secondaries.
* a special derivative of anti-entropy that runs in secondaries to snapshot
their local mesh gateway `CheckServiceNodes` and sync them into their upstream
FederationState in the primary (this works in conjunction with the
replication to distribute addresses for all mesh gateways in all DCs to all
other DCs)
* a "gateway locator" convenience object to make use of this data to choose
the addresses of gateways to use for any given RPC or gossip operation to a
remote DC. This gets data from the "retry join" logic in the agent and also
directly calls into the FSM.
* RPC (`:8300`) on the server sniffs the first byte of a new connection to
determine if it's actually doing native TLS. If so it checks the ALPN header
for protocol determination (just like how the existing system uses the
type-byte marker).
* 2 new kinds of protocols are exclusively decoded via this native TLS
mechanism: one for ferrying "packet" operations (udp-like) from the gossip
layer and one for "stream" operations (tcp-like). The packet operations
re-use sockets (using length-prefixing) to cut down on TLS re-negotiation
overhead.
* the server instances specially wrap the `memberlist.NetTransport` when running
with gateway federation enabled (in a `wanfed.Transport`). The general gist is
that if it tries to dial a node in the SAME datacenter (deduced by looking
at the suffix of the node name) there is no change. If dialing a DIFFERENT
datacenter it is wrapped up in a TLS+ALPN blob and sent through some mesh
gateways to eventually end up in a server's :8300 port.
* a new flag when launching a mesh gateway via `consul connect envoy` to
indicate that the servers are to be exposed. This sets a special service
meta when registering the gateway into the catalog.
* `proxycfg/xds` notice this metadata blob to activate additional watches for
the FederationState objects as well as the location of all of the consul
servers in that datacenter.
* `xds:` if the extra metadata is in place additional clusters are defined in a
DC to bulk sink all traffic to another DC's gateways. For the current
datacenter we listen on a wildcard name (`server.<dc>.consul`) that load
balances all servers as well as one mini-cluster per node
(`<node>.server.<dc>.consul`)
* the `consul tls cert create` command got a new flag (`-node`) to help create
an additional SAN in certs that can be used with this flavor of federation.
The Session API in Consul 1.7.0 and 1.7.1 is incompatible with prior versions of Consul.
This PR adds a note to our version-specific upgrade guide to guard against users upgrading before the fix in 1.7.2 is released.
The go-discover library supports Linode. This adds support for
discovering other Consul agents running on Linode. Consul has supported
this since [66b8c20][1] was merged, so this commit just updates the
documentation to match current features.
[1]: 66b8c20990
* Remove trailing whitespace in DNS forwarding guide.
* Add example for enabling reverse lookup of IP addrseses to .consul domain on systemd-resolved platforms
The option `username` does not work. Need to use user_name with underscore
> Authentication failed: Exactly one of Username and UserID must be provided for password authentication
The option `user_name` works, however, it's need to use `region`, `domain_name` in additional.
* add 1.12.2
* add envoy 1.13.0
* Introduce -envoy-version to get 1.10.0 passing.
* update old version and fix consul-exec case
* add envoy_version and fix check
* Update Envoy CLI tests to account for the 1.13 compatibility changes.
Co-authored-by: Matt Keeler <mkeeler@users.noreply.github.com>
* agent: measure blocking queries
* agent.rpc: update docs to mention we only record blocking queries
* agent.rpc: make go fmt happy
* agent.rpc: fix non-atomic read and decrement with bitwise xor of uint64 0
* agent.rpc: clarify review question
* agent.rpc: today I learned that one must declare all variables before interacting with goto labels
* Update agent/consul/server.go
agent.rpc: more precise comment on `Server.queriesBlocking`
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/agent/telemetry.html.md
agent.rpc: improve queries_blocking description
Co-Authored-By: Paul Banks <banks@banksco.de>
* agent.rpc: fix some bugs found in review
* add a note about the updated counter behavior to telemetry.md
* docs: add upgrade-specific note on consul.rpc.quer{y,ies_blocking} behavior
Co-authored-by: Paul Banks <banks@banksco.de>
* Expose Envoy /stats for statsd agents; Add testcases
* Remove merge conflict leftover
* Add support for prefix instead of path; Fix docstring to mirror these changes
* Add new config field to docs; Add testcases to check that /stats/prometheus is exposed as well
* Parametrize matchType (prefix or path) and value
* Update website/source/docs/connect/proxies/envoy.md
Co-Authored-By: Paul Banks <banks@banksco.de>
Co-authored-by: Paul Banks <banks@banksco.de>
Update the description for the Helm chart's connectInject.imageEnvoy
parameter to reflect the correct organization name for images published by
EnvoyProxy.io.
* Updates to the Txn API for namespaces
* Update agent/consul/txn_endpoint.go
Co-Authored-By: R.B. Boyer <rb@hashicorp.com>
Co-authored-by: R.B. Boyer <public@richardboyer.net>
This commit changes the health check example shown for the
success/failures_before_passing option to correctly show that the value
of `checks` is an array of objects, not an object.
Added text clarifying these check parameters are available in Consul
1.7.0 and later.
Expanded the health check to provide a more complete configuration
example.
Resolves#7114.
The backing RPC already existed but the endpoint will be useful for other service syncing processes such as consul-k8s as this endpoint can return all services registered with a node regardless of namespacing.
Removing automatic connection wording for applications for the time being. From @blake
> They can automatically establish TLS connections without being aware that TLS is happening. They are aware that they’re routed through the Connect proxy, the app has to configure itself to use the local upstream port.
Currently when using the built-in CA provider for Connect, root certificates are valid for 10 years, however secondary DCs get intermediates that are valid for only 1 year. There is no mechanism currently short of rotating the root in the primary that will cause the secondary DCs to renew their intermediates.
This PR adds a check that renews the cert if it is half way through its validity period.
In order to be able to test these changes, a new configuration option was added: IntermediateCertTTL which is set extremely low in the tests.
* Add CreateCSRWithSAN
* Use CreateCSRWithSAN in auto_encrypt and cache
* Copy DNSNames and IPAddresses to cert
* Verify auto_encrypt.sign returns cert with SAN
* provide configuration options for auto_encrypt dnssan and ipsan
* rename CreateCSRWithSAN to CreateCSR
* docs/connect add link to intentions and minor phrasing change
* docs/connect pluralize 'applications'
* Update website/source/docs/connect/connect-internals.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Renamed structs.IntentionWildcard to structs.WildcardSpecifier
* Refactor ACL Config
Get rid of remnants of enterprise only renaming.
Add a WildcardName field for specifying what string should be used to indicate a wildcard.
* Add wildcard support in the ACL package
For read operations they can call anyAllowed to determine if any read access to the given resource would be granted.
For write operations they can call allAllowed to ensure that write access is granted to everything.
* Make v1/agent/connect/authorize namespace aware
* Update intention ACL enforcement
This also changes how intention:read is granted. Before the Intention.List RPC would allow viewing an intention if the token had intention:read on the destination. However Intention.Match allowed viewing if access was allowed for either the source or dest side. Now Intention.List and Intention.Get fall in line with Intention.Matches previous behavior.
Due to this being done a few different places ACL enforcement for a singular intention is now done with the CanRead and CanWrite methods on the intention itself.
* Refactor Intention.Apply to make things easier to follow.
* added disclaimer about network segments due to Serf limitations
using work made at https://github.com/hashicorp/consul/pull/6558 by @thepomeranian
* Lowercasing functionality name
* Update website/source/docs/enterprise/network-segments/index.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
Co-authored-by: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Azure MSI documentation
Adding in note about support for Azure MSI authentication method for Cloud auto-join
* fixing text formatting
fixing text formatting
* missing word
missing word - variable
* Update website/source/docs/agent/cloud-auto-join.html.md
Language change to be specific about where the security risk mitigation is concerned
Co-Authored-By: Jack Pearkes <jackpearkes@gmail.com>
Co-authored-by: Jack Pearkes <jackpearkes@gmail.com>
The global.bootstrapACLs key in the Helm chart docs was inadvertently
moved to a top-level key in commit 12e6ef8, which is incorrect.
This commit reverts that error.
* Handle discard all logfiles properly
Fixes https://github.com/hashicorp/consul/issues/6892.
The [docs](https://www.consul.io/docs/agent/options.html#_log_rotate_max_files) are stating:
> -log-rotate-max-files - to specify the maximum number of older log
> file archives to keep. Defaults to 0 (no files are ever deleted). Set to
> -1 to disable rotation and discard all log files.
But the `-1` case was not implemented and led to a panic when being
used.
Co-Authored-By: Freddy <freddygv@users.noreply.github.com>
- website: embed yt videos on intro pages
- for /docs/connect
- for /intro
- css to handle iframe responding at smaller viewports
- Update consul connect video with introductory description. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
- Update consul connect intro with introductory description. Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
Update -retry-join documentation to explicitly state the option can be
specified multiple times. Add corresponding config example showing
multiple join addresses.
* relax requirements for auto_encrypt on server
* better error message when auto_encrypt and verify_incoming on
* docs: explain verify_incoming on Consul clients.
Also update the Docs and fixup the HTTP API to return proper errors when someone attempts to use Namespaces with an OSS agent.
Add Namespace HTTP API docs
Make all API endpoints disallow unknown fields
The listener ports specified in the headings for the HTTP and HTTP2
examples do not match the ports in the corresponding service
registration configurations.
This commit changes the port specified in the heading for the HTTP
listener to match the port used in the service registration example.
In addition, the listener_port specified for the HTTP2 listener is
modified to match the port number specified in the heading.
- Remove duplicate install instructions from the Helm Chart page and
kept them in Running Consul
- Renamed Helm Chart to Helm Chart Reference because that's mostly what
it contains (along with some examples)
- Renamed Running Consul to Installing Consul
- Changed instructions to be for installing using Helm 3 and added
notes if using Helm 2
- Used release name "hashicorp" so subsequent instructions can be more
concise and pastable, e.g. "port forward to svc/hashicorp-consul-server" vs. "port
forward to svc/<your release name>-consul-server"
- Use config.yaml as the name for the override values file since it
differentiates from the default values.yaml file and its the name of the
file used in the helm docs
(https://helm.sh/docs/intro/using_helm/#customizing-the-chart-before-installing)
* Adds 'limits' field to the upstream configuration of a connect proxy
This allows a user to configure the envoy connect proxy with
'max_connections', 'max_queued_requests', and 'max_concurrent_requests'. These
values are defined in the local proxy on a per-service instance basis
and should thus NOT be thought of as a global-level or even service-level value.
* Update AWS SDK to use PCA features.
* Add AWS PCA provider
* Add plumbing for config, config validation tests, add test for inheriting existing CA resources created by user
* Unparallel the tests so we don't exhaust PCA limits
* Merge updates
* More aggressive polling; rate limit pass through on sign; Timeout on Sign and CA create
* Add AWS PCA docs
* Fix Vault doc typo too
* Doc typo
* Apply suggestions from code review
Co-Authored-By: R.B. Boyer <rb@hashicorp.com>
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Doc fixes; tests for erroring if State is modified via API
* More review cleanup
* Uncomment tests!
* Minor suggested clean ups
- Remove incorrect statement that `LockDelay` must be greater than 0
- Add sentence to the top of the page pointing to the internal document
describing the sessions mechanism for more context
* Support Connect CAs that can't cross sign
* revert spurios mod changes from make tools
* Add log warning when forcing CA rotation
* Fixup SupportsCrossSigning to report errors and work with Plugin interface (fixes tests)
* Fix failing snake_case test
* Remove misleading comment
* Revert "Remove misleading comment"
This reverts commit bc4db9cabed8ad5d0e39b30e1fe79196d248349c.
* Remove misleading comment
* Regen proto files messed up by rebase
* updating the landing page with jtbd
* changed the buttons to pink
* updating CSS based on John's help
* updating a use case
* updating the language and rearranging the guides
* adding icons
* fixed image width
* fixing buttons and updating traffic splitting language.
Fix spelling errors, API doc inconsistencies, and formatting issues.
* Fix several spelling errors.
* Prepend / to v1/event/list path in Watches.
* Rename script handlers to match Watch type.
* Remove /v1 path prefix on service health API endpoints.
Makes request path consistent with the rest of the HTTP API
documentation which does not include the /v1 prefix.
* Fix bracket formatting issue on Telemetry page.
The HTML codes used for brackets inside of the code block are not
interpolated, and are shown as literal strings.
Replace the numeric HTML codes with the intended character value to
fix display formatting.
Also placed variable reference on agent/options.html inside code block
for consistency with the presentation of other options on the page.
* Add missing word to Coordinate.Node docstring.
Resolves#6014
* Allow RSA CA certs for consul and vault providers to correctly sign EC leaf certs.
* Ensure key type ad bits are populated from CA cert and clean up tests
* Add integration test and fix error when initializing secondary CA with RSA key.
* Add more tests, fix review feedback
* Update docs with key type config and output
* Apply suggestions from code review
Co-Authored-By: R.B. Boyer <rb@hashicorp.com>
Updating all .io Community sites to direct practitioners to the Forum as the first medium for communicating with other users and HashiCorp employees. Deleted Gitter link and Google Group link, as these will be phased out over the next few months. Updated what appeared to be a typo on the page description. Chatted with Nic Jackson before submitting PR.
* Changed Guides to Learn in the top nav and added utm parameters to the guide index page
* Update website/source/docs/guides/index.html.md
* Update website/source/docs/guides/index.html.md
* Update website/source/layouts/layout.erb
A check may be set to become passing/critical only if a specified number of successive
checks return passing/critical in a row. Status will stay identical as before until
the threshold is reached.
This feature is available for HTTP, TCP, gRPC, Docker & Monitor checks.
Add text listing Consul's L7 features (via Envoy). Re-organize text to
flow similarly to Istio section.
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
Fixes#2742
Previously the docs didn't clarify that if a server restarts as a client then force-leave won't lead to removing the node from the raft config. This is because the node, which is alive after a restart, will refute messages about it having left . These messages about members leaving are in turn what trigger Consul's leader to remove a server from raft.
Fixes: #5396
This PR adds a proxy configuration stanza called expose. These flags register
listeners in Connect sidecar proxies to allow requests to specific HTTP paths from outside of the node. This allows services to protect themselves by only
listening on the loopback interface, while still accepting traffic from non
Connect-enabled services.
Under expose there is a boolean checks flag that would automatically expose all
registered HTTP and gRPC check paths.
This stanza also accepts a paths list to expose individual paths. The primary
use case for this functionality would be to expose paths for third parties like
Prometheus or the kubelet.
Listeners for requests to exposed paths are be configured dynamically at run
time. Any time a proxy, or check can be registered, a listener can also be
created.
In this initial implementation requests to these paths are not
authenticated/encrypted.
The fields in the certs are meant to hold the original binary
representation of this data, not some ascii-encoded version.
The only time we should be colon-hex-encoding fields is for display
purposes or marshaling through non-TLS mediums (like RPC).
- fix instructions for CoreDNS (it updated)
- fix instructions for new component names
- recommend installing with the name 'consul'
- add disclaimer that catalog sync is not always required
- clean up example values.yaml files
* website: Update middleman-hashicorp container and Gemfile.lock
Time marches on, and so do security vulnerabilities in Nokogiri. So it's time
for a new container.
As with last time, here's a reminder for the next person who needs to update
this:
- You shouldn't just update the dependency in Gemfile.lock, because your build
times will go to heck as you compile Nokogiri from source on every run. So you
need an updated container with all the dependencies.
- To update the container, you need to push a new tag to the middleman-hashicorp
repo. Teamcity does the rest, and will ship a new container to Docker Hub
(unless its credentials are out of date, in which case go ask team-eng-serv.)
- Once that's pushed:
- Update Makefile
- Update the Gemfile
- Delete Gemfile.lock
- `make website` until it comes up, then ctrl-C
- Commit the changes
* website: Specify a different json version in Gemfile.lock
The Consul website uses different containers for preview and deploy, and this
oddball JSON version was causing issues. This commit sacrifices a little bit
of preview startup speed for (hopefully) working deploys.
- Bootstrap escape hatches are OK.
- Public listener/cluster escape hatches are OK.
- Upstream listener/cluster escape hatches are not supported.
If an unsupported escape hatch is configured and the discovery chain is
activated log a warning and act like it was not configured.
Fixes#6160
* website: update the vs. envoy and proxies page
This is the second result on Google for "consul envoy" and
it seemed like it needed a bit of an upgrade to help clarify the
current state.
* Update website/source/intro/vs/proxies.html.md
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
* Update website/source/intro/vs/proxies.html.md
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
* Update website/source/intro/vs/proxies.html.md
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
* Update website/source/intro/vs/proxies.html.md
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
* Apply suggestions from code review
Co-Authored-By: Judith Malnick <judith.patudith@gmail.com>
Add parameter local-only to operator keyring list requests to force queries to only hit local servers (no WAN traffic).
HTTP API: GET /operator/keyring?local-only=true
CLI: consul keyring -list --local-only
Sending the local-only flag with any non-GET/list request will result in an error.
The main change is that we no longer filter service instances by health,
preferring instead to render all results down into EDS endpoints in
envoy and merely label the endpoints as HEALTHY or UNHEALTHY.
When OnlyPassing is set to true we will force consul checks in a
'warning' state to render as UNHEALTHY in envoy.
Fixes#6171
* Update go-bexpr to v0.1.1
This brings in:
• `in`/`not in` operators to do substring matching
• `matches` / `not matches` operators to perform regex string matching.
* Add the capability to auto-generate the filtering selector ops tables for our docs
This fixes pathological cases where the write throughput and snapshot size are both so large that more than 10k log entries are written in the time it takes to restore the snapshot from disk. In this case followers that restart can never catch up with leader replication again and enter a loop of constantly downloading a full snapshot and restoring it only to find that snapshot is already out of date and the leader has truncated its logs so a new snapshot is sent etc.
In general if you need to adjust this, you are probably abusing Consul for purposes outside its design envelope and should reconsider your usage to reduce data size and/or write volume.
* Bad link in encryption docs
* clarifying the guide link
* Update website/source/docs/agent/encryption.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/agent/encryption.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* add connect gateway guide
* Remove stray space
Co-Authored-By: Freddy <freddygv@users.noreply.github.com>
* Specify stanza and exact options
Co-Authored-By: Freddy <freddygv@users.noreply.github.com>
* incorporate comments from freddy
* integrate feedback from matt
* make snippets all json
* incorporate more comments from matt
* added links
* incorporate comments from neena on google doc draft
* make learn lnks relative
* clarify that gateways are new
* change socat to netcat
* add more description about replication token permissions
* Apply suggestions from code review
Co-Authored-By: Matt Keeler <mkeeler@users.noreply.github.com>
* add the prerequisite to enable centralized service config
* finish adding docs links
* website: link to 1.6.0 beta in downloads page
* website: reorganize intention replication/ca federation
* website: remove announcement bar
* Update website/source/docs/connect/connect-internals.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* website: update homepage and service mesh page
Aligning messaging to current product.
* website: fix link TODOs
* Add Mesh Gateway to mesh page, update use case wording
* connect: allow overriding envoy listener bind_address
* Update agent/xds/config.go
Co-Authored-By: Kyle Havlovitz <kylehav@gmail.com>
* connect: allow overriding envoy listener bind_port
* envoy: support unix sockets for grpc in bootstrap
Add AgentSocket BootstrapTplArgs which if set overrides the AgentAddress
and AgentPort to generate a bootstrap which points Envoy to a unix
socket file instead of an ip:port.
* Add a test for passing the consul addr as a unix socket
* Fix config formatting for envoy bootstrap tests
* Fix listeners test cases for bind addr/port
* Update website/source/docs/connect/proxies/envoy.md
* Add ui-content-path flag
* tests complete, regex validator on string, index.html updated
* cleaning up debugging stuff
* ui: Enable ember environment configuration to be set via the go binary at runtime (#5934)
* ui: Only inject {{.ContentPath}} if we are makeing a prod build...
...otherwise we just use the current rootURL
This gets injected into a <base /> node which solves the assets path
problem but not the ember problem
* ui: Pull out the <base href=""> value and inject it into ember env
See previous commit:
The <base href=""> value is 'sometimes' injected from go at index
serve time. We pass this value down to ember by overwriting the ember
config that is injected via a <meta> tag. This has to be done before
ember bootup.
Sometimes (during testing and development, basically not production)
this is injected with the already existing value, in which case this
essentially changes nothing.
The code here is slightly abstracted away from our specific usage to
make it easier for anyone else to use, and also make sure we can cope
with using this same method to pass variables down from the CLI through
to ember in the future.
* ui: We can't use <base /> move everything to javascript (#5941)
Unfortuantely we can't seem to be able to use <base> and rootURL
together as URL paths will get doubled up (`ui/ui/`).
This moves all the things that we need to interpolate with .ContentPath
to the `startup` javascript so we can conditionally print out
`{{.ContentPath}}` in lots of places (now we can't use base)
* fixed when we serve index.html
* ui: For writing a ContentPath, we also need to cope with testing... (#5945)
...and potentially more environments
Testing has more additional things in a separate index.html in `tests/`
This make the entire thing a little saner and uses just javascriopt
template literals instead of a pseudo handbrake synatx for our
templating of these files.
Intead of just templating the entire file this way, we still only
template `{{content-for 'head'}}` and `{{content-for 'body'}}`
in this way to ensure we support other plugins/addons
* build: Loosen up the regex for retrieving the CONSUL_VERSION (#5946)
* build: Loosen up the regex for retrieving the CONSUL_VERSION
1. Previously the `sed` replacement was searching for the CONSUL_VERSION
comment at the start of a line, it no longer does this to allow for
indentation.
2. Both `grep` and `sed` where looking for the omment at the end of the
line. We've removed this restriction here. We don't need to remove it
right now, but if we ever put the comment followed by something here the
searching would break.
3. Added `xargs` for trimming the resulting version string. We aren't
using this already in the rest of the scripts, but we are pretty sure
this is available on most systems.
* ui: Fix erroneous variable, and also force an ember cache clean on build
1. We referenced a variable incorrectly here, this fixes that.
2. We also made sure that every `make` target clears ember's `tmp` cache
to ensure that its not using any caches that have since been edited
everytime we call a `make` target.
* added docs, fixed encoding
* fixed go fmt
* Update agent/config/config.go
Co-Authored-By: R.B. Boyer <public@richardboyer.net>
* Completed Suggestions
* run gofmt on http.go
* fix testsanitize
* fix fullconfig/hcl by setting correct 'want'
* ran gofmt on agent/config/runtime_test.go
* Update website/source/docs/agent/options.html.md
Co-Authored-By: Hans Hasselberg <me@hans.io>
* Update website/source/docs/agent/options.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* remove contentpath from redirectFS struct
* Support for maximum size for Output of checks
This PR allows users to limit the size of output produced by checks at the agent
and check level.
When set at the agent level, it will limit the output for all checks monitored
by the agent.
When set at the check level, it can override the agent max for a specific check but
only if it is lower than the agent max.
Default value is 4k, and input must be at least 1.
* Moved the glossary to a new page and removed the advanced warnings from all internals docs.
* Update website/source/layouts/docs.erb
Co-Authored-By: Judith Malnick <judith@hashicorp.com>
* Updates based on PR feedback
* Update website/source/docs/internals/index.html.md
* Update website/source/docs/internals/index.html.md
* Update website/source/docs/internals/index.html.md
* Update website/source/docs/internals/index.html.md
* Update website/source/docs/internals/index.html.md
* Upating the term node to be more clear
* Update website/source/docs/internals/architecture.html.md
* Update website/source/docs/internals/architecture.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Addressing the failure detection comment
This allows addresses to be tagged at the service level similar to what we allow for nodes already. The address translation that can be enabled with the `translate_wan_addrs` config was updated to take these new addresses into account as well.
* clarify possibilities for centralized proxy configuration
* add line breaks to config entries file
* add info about centralized config to built in proxy doc
* mondify connect landing page to help with navigation
* move internals details to its own page
* link fixes and shortening text on main page
* put built-in proxy options on its own page
* add configuration details for connect
* clarify security title and add observability page
* reorganize menu
* remove observability from configuration section
* Update website/source/docs/connect/configuration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/connect/index.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/agent/config_entries.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/connect/configuration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* rename connect section to include service mesh
* reorganize sections per suggestions from paul
* add configuration edits from paul
* add internals edits from paul
* add observability edits from paul
* reorganize pages and menu
* Update website/source/docs/connect/configuration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* menu corrections and edits
* incorporate some of pauls comments
* incorporate more of pauls comments
* Update website/source/docs/connect/configuration.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/connect/index.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/connect/index.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* Update website/source/docs/connect/registration.html.md
Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
* incorporate kaitlin and pavanni feedback
* add redirect
* fix conflicts in index file
* Resolve conflicts in index file
* correct links for new organization
* Update website/source/docs/connect/proxies.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/connect/registration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/connect/registration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* Update website/source/docs/connect/registration.html.md
Co-Authored-By: Paul Banks <banks@banksco.de>
* add title to service registration page
* Upgrade xDS (go-control-plane) API to support Envoy 1.10.
This includes backwards compatibility shim to work around the ext_authz package rename in 1.10.
It also adds integration test support in CI for 1.10.0.
* Fix go vet complaints
* go mod vendor
* Update Envoy version info in docs
* Update website/source/docs/connect/proxies/envoy.md
The policy in the time-of-day Sentinel example incorrectly references
the top-level time.hour constant. This is actually the same as the
time.Hour Go value, so in other words, 3600000000000 (the int64 value
representing the time in nanoseconds).
This is corrected by just using time.now.hour instead.
* bump middleman-hashicorp to 0.3.40 and exclude guide rendering
* add notes to Makefile for volume mounts hack PR#5847
* make note of the PR number in the comment
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.
Hans Hasselberg