packages/coredns-deployment
1
0
Fork 0
mirror of https://github.com/notherealmarco/coredns-deployment.git synced 2025-05-05 12:32:34 +02:00
Code Issues Projects Releases Packages 1 Wiki Activity Actions

clean up docs (#166)

Browse source
This commit is contained in:
Chris O'Haver 2019-05-14 12:05:29 -04:00 • committed by GitHub
parent 910ada176e
commit f1dac88b86
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 83 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

100
kubernetes/migration/README.md
View file

@ -1,54 +1,86 @@
# K8s/CoreDNS Corefile Migration Tools # K8s/CoreDNS Corefile Migration Tools
This Go library provides a set of functions to help handle migrations of CoreDNS Corefiles to be compatible with new versions of CoreDNS. The task of upgrading CoreDNS is the responsibility of a variety of Kubernetes management tools (e.g. kubeadm and others), and the precise behavior may be different for each one. This library abstracts some basic helper functions that make this easier to implement. This Go library provides a set of functions to help handle migrations of CoreDNS Corefiles to be compatible
with new versions of CoreDNS. The task of upgrading CoreDNS is the responsibility of a variety of Kubernetes
management tools (e.g. kubeadm and others), and the precise behavior may be different for each one. This
library abstracts some basic helper functions that make this easier to implement.
## Proposed functions: ## Notifications
`Deprecated(fromCoreDNSVersion, toCoreDNSVersion, corefile string) []string`: returns a list of deprecated plugins or directives present in the Corefile. Each string returned is a warning, e.g. "plugin 'foo' is deprecated." An empty list returned means there are no deprecated plugins/options present in the Corefile. Several functions in the library return a list of Notices. Each Notice is a warning of a feature deprecation,
an unsupported plugin/option, or a new required plugin/option added to the Corefile. A Notice has a `ToString()`
For display to an end user. e.g.
`Removed(fromCoreDNSVersion, toCoreDNSVersion, corefile string) []string`: returns a list of removed plugins or directives present in the Corefile. Each string returned is a warning, e.g. "plugin 'foo' is no longer supported." An empty list returned means there are no removed plugins/options present in the Corefile. ```
Plugin "foo" is deprecated in <version>. It is replaced by "bar".
Plugin "bar" is removed in <version>. It is replaced by "qux".
Option "foo" in plugin "bar" is added as a default in <version>.
Plugin "baz" is unsupported by this migration tool in <version>.
```
`Migrate(fromCoreDNSVersion, toCoreDNSVersion, corefile string, deprecations boolean) (string, error)`: returns an automatically migrated version of the Corefile, or an error if it cannot. It should:
## Functions
`Deprecated(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error)`
Deprecated returns a list of deprecation notices affecting the given Corefile. Notices are returned for
any deprecated, removed, or ignored plugins/directives present in the Corefile. Notices are also returned for
any new default plugins that would be added in a migration. Notices
`Migrate(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string, deprecations bool) (string, error)`
Migrate returns a migrated version of the Corefile, or an error if it cannot. It will:
* replace/convert any plugins/directives that have replacements (e.g. _proxy_ -> _forward_) * replace/convert any plugins/directives that have replacements (e.g. _proxy_ -> _forward_)
* return an error if replacable plugins/directives cannot be converted (e.g. proxy _options_ not available in _forward_) * return an error if replacable plugins/directives cannot be converted (e.g. proxy _options_ not available in _forward_)
* remove plugins/directives that do not have replacements (e.g. kubernetes `upstream`) * remove plugins/directives that do not have replacements (e.g. kubernetes `upstream`)
* add in any new default plugins where applicable if they are not already present (e.g. adding _loop_ plugin when it was added). This will have to be case by case, and could potentially get complicated. * add in any new default plugins where applicable if they are not already present (e.g. adding _loop_ plugin when it was added).
* if _deprecations_ is set to true, also migrate deprecated plugins/directives. This will have to be case by case, and could potentially get complicated.
* If deprecations is true, deprecated plugins/options will be migrated as soon as they are deprecated.
`Unsupported(fromCoreDNSVersion, toCoreDNSVersion, corefile string) []string`: returns a list of plugins that are not recognized/supported by the migration tool (but may still be valid in CoreDNS). We must handle all the default plugins, and we should make an effort to handle the most common non-default plugins. Each string returned is a warning, e.g. "plugin 'foo' is not supported by the migration tool." An empty list returned means there are no unsupported plugins/options present in the Corefile. * If deprecations is false, deprecated plugins/options will be migrated only once they become removed or ignored.
`Default(fromK8sVersion, corefile string) bool`: returns `true` if the Corefile is the default for a that version of Kubernetes. If `fromK8sVersion` is omitted, returns `true` if the Corefile is the default for any version. Some degree of safe fuzzy matching should be employed here to accept custom cluster domain names and IP addresses, as well as white space.
`CheckCorefile(coreDNSVersion, corefile string) bool`: returns true if the configuration is valid for the given version. This is intended as a sanity checks to make sure a Corefile can be loaded by CoreDNS, e.g. by calling `setup()` for each plugin used. This won't work for custom compilations CoreDNS - e.g. one compiled with external plugins are used.
`Released(dockerImageID string) bool`: returns `true` if `dockerImageID` matches any _released_ image of CoreDNS. This includes all released verisons of CoreDNS, not just those associted with Kubernetes releases.
Globally, `toCoreDNSVersion` must always be higher than `fromCoreDNSVersion`. Supporting downward migrations may be possible, but I don't think necessary to support at this time, so we should expressly forbid downward migrations for now. That said, if a Corefile is at default then a downgrade is very easy (since no migration is required). It's up to the K8s installer to decide if they want to support that.
## Command Line Converter `Unsupported(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error)`
We should also write a simple command line tool that allows someone to use these functions via the command line. Unsupported returns a list Notices for plugins/options that are unhandled by this migration tool,
but may still be valid in CoreDNS. Currently, only a subset of plugins included by default in CoreDNS are supported
by this tool.
E.g.
``` `Default(k8sVersion, corefileStr string) bool`
Usage:
corefile-tool deprecated --from <coredns-version> --to <coredns-version> --corefile <path>
corefile-tool removed --from <coredns-version> --to <coredns-version> --corefile <path> [--deprecations]
corefile-tool migrate --from <coredns-version> --to <coredns-version> --corefile <path>
etc ...
```
## Example of Usage Default returns true if the Corefile is the default for a given version of Kubernetes.
Or, if k8sVersion is empty, Default returns true if the Corefile is the default for any version of Kubernetes.
This is an example of how these tools could be used by an installer/upgrader...
0. Check `Default()`, if the Corefile is a default, simply re-deploy the new default over top the old one. No migration needed. If the Corefile is not a default, continue... `Released(dockerImageSHA string) bool`
1. Check `Deprecated()`, if anything is deprecated, warn user, but continue install.
2. Check `Unsupported()`, if anything is unsupported, abort and warn user (allow user to override to pass this). Released returns true if dockerImageSHA matches any released image of CoreDNS.
3. Call `Migrate()`, if there is an error, abort and warn user.
4. If there is no error, pause and ask user if they want to continue with the migration. If the starting Corefile was at defaults, proceed use the migrated corefile.
`ValidVersions() []string`
ValidVersions returns a list of all versions supported by this tool.
## Command Line Converter Example
An example use of this library is provided [here](../corefile-tool/).
## Kubernetes Cluster Managemnt Tool Usage
This is an example flow of how this library could be used by a Kubernetes cluster management tool to perform a
Corefile migration during an upgrade...
0. Check `Released()` to verify that the installed version of CoreDNS is an official release.
1. Check `Default()`, if the Corefile is a default, simply re-deploy the new default over top the old one. No migration needed.
If the Corefile is not a default, continue...
2. Check `Deprecated()`, if anything is deprecated, warn user, but continue install.
3. Check `Unsupported()`, if anything is unsupported, abort and warn user (allow user to override to pass this).
4. Call `Migrate()`, if there is an error, abort and warn user.
5. If there is no error, pause and ask user if they want to continue with the migration. If the starting Corefile was at defaults,
proceed use the migrated Corefile.

13
kubernetes/migration/migrate.go
View file

@ -12,14 +12,15 @@ import (
"github.com/coredns/deployment/kubernetes/migration/corefile" "github.com/coredns/deployment/kubernetes/migration/corefile"
) )
// Deprecated returns a list of deprecated, removed, ignored and new default plugins or directives present in the Corefile. // Deprecated returns a list of deprecation notifications affecting the guven Corefile. Notifications are returned for
// Each Notice returned is a warning, e.g. "plugin 'foo' is deprecated." An empty list returned means there are no // any deprecated, removed, or ignored plugins/directives present in the Corefile. Notifications are also returned for
// deprecated, removed, ignored or new default plugins/options present in the Corefile. // any new default plugins that would be added in a migration.
func Deprecated(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error) { func Deprecated(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error) {
return getStatus(fromCoreDNSVersion, toCoreDNSVersion, corefileStr, all) return getStatus(fromCoreDNSVersion, toCoreDNSVersion, corefileStr, all)
} }
// Unsupported returns a list of plugins that are not recognized/supported by the migration tool (but may still be valid in CoreDNS). // Unsupported returns a list notifications of plugins/options that are not handled supported by this migration tool,
// but may still be valid in CoreDNS.
func Unsupported(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error) { func Unsupported(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string) ([]Notice, error) {
return getStatus(fromCoreDNSVersion, toCoreDNSVersion, corefileStr, unsupported) return getStatus(fromCoreDNSVersion, toCoreDNSVersion, corefileStr, unsupported)
} }
@ -121,7 +122,9 @@ func getStatus(fromCoreDNSVersion, toCoreDNSVersion, corefileStr, status string)
return notices, nil return notices, nil
} }
// Migrate returns version of the Corefile migrated to toCoreDNSVersion, or an error if it cannot. // Migrate returns the Corefile converted to toCoreDNSVersion, or an error if it cannot.
// If deprecations is true, deprecated plugins/options will be migrated as soon as they are deprecated.
// If deprecations is false, deprecated plugins/options will be migrated only once they become removed or ignored.
func Migrate(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string, deprecations bool) (string, error) { func Migrate(fromCoreDNSVersion, toCoreDNSVersion, corefileStr string, deprecations bool) (string, error) {
err := validateVersions(fromCoreDNSVersion, toCoreDNSVersion) err := validateVersions(fromCoreDNSVersion, toCoreDNSVersion)
if err != nil { if err != nil {

15
kubernetes/migration/notice.go
View file

@ -36,10 +36,13 @@ func (n *Notice) ToString() string {
} }
const ( const (
deprecated = "deprecated" // plugin/option is deprecated in CoreDNS // The following statuses are used to indicate the state of support/deprecation in a given release.
ignored = "ignored" // plugin/option is ignored by CoreDNS deprecated = "deprecated" // deprecated, but still completely functional
removed = "removed" // plugin/option has been removed from CoreDNS ignored = "ignored" // if included in the corefile, it will be ignored by CoreDNS
unsupported = "unsupported" // plugin/option is not supported by the migration tool removed = "removed" // completely removed from CoreDNS, and would cause CoreDNS to exit if present in the Corefile
newdefault = "newdefault" // plugin/option was added to the default corefile newdefault = "newdefault" // added to the default corefile. CoreDNS may not function properly if it is not present in the corefile.
all = "all" // all plugin/option that are deprecated, ignored, removed and new defaults. unsupported = "unsupported" // the plugin/option is not supported by the migration tool
// The following statuses are used for selecting/filtering notifications
all = "all" // show all statuses
) )