catalog

package module
v0.4.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 7, 2023 License: Apache-2.0 Imports: 18 Imported by: 0

README

consul_catalog

Name

consul_catalog - enables serving A resources for tagged consul services

Description

This plugin reads services from the Consul Catalog, and serves A records to them if tagged with specified tags.

Build

Add to plugin.cfg with:

consul_catalog:github.com/cbpowell/coredns-consul

And then follow CoreDNS custom build instructions.

Syntax

consul_catalog [TAGS...]

With only the plugin specified, the consul_catalog plugin will default to the "coredns.enabled" tag. If TAGS is specified, only services matching these exact tags will be considered for serving.

consul_catalog [TAGS...] {
    endpoint URL
    # to enable tls encryption, might need your cluster's CA certificates installed!
    scheme https
    token TOKEN
    acl_metadata_tag META_TAG
    acl_zone ZONE_NAME ZONE_CIDR
    acl_ignore_tag IGNORE_TAG
    service_proxy PROXY_TAG PROXY_SERVICE
    alias_tag ALIAS_TAG
    config_kv_path CONSUL_KV_PATH
    ttl TTL
}
  • endpoint specifies the URL where to find consul catalog, by default consul.service.consul:8500.
  • token specifies the token to authenticate with the consul service.
  • acl_metadata_tag specifies the Consul metadata tag to read acl rules from, by default coredns-acl. An ACL rule looks like: allow network1; deny network2. Rules are interpreted in order of appearance on the corresponding service's metatag.
  • acl_zone adds a zone named ZONE_NAME with corresponding ZONE_CIDR range.
  • acl_ignore_tag If specified, services tagged with IGNORE_TAG will not have any ACLs enforced. This is also useful if metadata cannot be added to the Consul service definition (e.g. Vault).
  • service_proxy If specified, services tagged with PROXY_TAG will respond with the address for PROXY_SERVICE instead.
  • alias_tag If specified, services tagged with ALIAS_TAG=[comma-separated list of services aliases] will also be accessible via the specified aliases.
  • config_kv_path If specified, consul's kv store will be queried for CONSUL_KV_PATH and specified entries will be served before querying for catalog records. The value at CONSUL_KV_PATH must contain json in following this schema: 
    {
    "myCatalogService": {
        "target": "serviceA", // the name of a service registered with consul
        "acl": ["allow network1", "deny network2"] // a list of ACL rules
    },
    "myServiceProxyService": {
        "target": "@service_proxy", // a run-time alias for acl_zone's PROXY_SERVICE
        "acl": ["allow network1"],
    }
}
  • ttl specifies the TTL in golang duration strings returned for matching service queries, by default 5 minutes.

Ready

This plugin reports readiness to the ready plugin. This will happen after it has synced to the Consul Catalog API.

Examples

Handle all the queries in the example.com zone, first by looking into hosts, then consul, and finally a zone file. Queries for services in the catalog at consul.service.consul:8500 with a coredns.enabled tag will be answered with the addresses for $SERVICE_NAME.services.consul. If the service also includes a traefik.enabled tag, queries will be answered with the addresses for traefik.service.consul.

example.com {
    hosts {
        10.0.0.42 fourtytwo.example.com
        fallthrough
    }

    consul_catalog coredns.enabled {
        endpoint consul.service.consul:8500
        
        // Token needs read access to services and nodes
        token CONSUL_ACL_TOKEN
        
        // Use coredns-consul metadata tag to define ACL (like "allow trusted")
        acl_metada_tag coredns-consul
        
        // Do not apply ACLs to services tagged with "coredns.ignoreacl"
        acl_ignore_tag coredns.ignoreacl
        
        // Use traefik as service proxy, looking for same tag used to enable traefik
        service_proxy traefik.enable=true traefik
        
        // Specify alias tags
        // Services needs associated tag with list of aliases, i.e "coredns.alias=alias1,alias2"
        // Allowing access via "alias1.example.com" and "alias2.example.com"
        alias_tag coredns.alias
        
        // Define ACLs
        acl_zone trusted 10.0.0.0/24
        acl_zone guests 192.168.10.0/24
        acl_zone iot 192.168.20.0/24
        acl_zone public 0.0.0.0/24
        ttl 10m
    }

    # if a SOA is specified in this file, it'll be added
    # to responses from consul services
    file zones/example.com
}

// This zone needs to be retained for coredns-consul to work!
consul {
    # Forward all requests to consul
    forward . 10.0.0.42:8600 10.0.0.43:8600 10.0.0.44:8600 {
        policy sequential
    }
}

. {
    forward . 1.1.1.1 8.8.8.8
    errors
    cache
}

Documentation

Overview

Copyright © 2022 Roberto Hidalgo <coredns-consul@un.rob.mx> Modified by Charles Powell, 2023 SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <coredns-consul@un.rob.mx> Modified by Charles Powell, 2023 SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <coredns-consul@un.rob.mx> Modified by Charles Powell, 2023 SPDX-License-Identifier: Apache-2.0

Copyright © 2022 Roberto Hidalgo <coredns-consul@un.rob.mx> SPDX-License-Identifier: Apache-2.0

Index

Constants

This section is empty.

Variables

View Source 
var Log = clog.NewWithPlugin("consul_catalog")

Functions

func CreateClient 

func CreateClient(scheme, endpoint, token string) (catalog ClientCatalog, kv KVClient, err error)

CreateClient initializes the consul catalog client.

Types

type Catalog 

type Catalog struct {
	sync.RWMutex
	Endpoint     string
	Scheme       string
	Tag          string
	ACLIgnoreTag string
	AliasTag     string

	FQDN         []string
	TTL          uint32
	Token        string
	ProxyService string
	ProxyTag     string
	Networks     map[string]*net.IPNet
	MetadataTag  string
	ConfigKey    string
	Next         plugin.Handler
	Zone         string
	// contains filtered or unexported fields
}

Catalog holds published Consul Catalog services.

func New 

func New() *Catalog

New returns a Catalog plugin.

func (*Catalog) FetchConfig 

func (c *Catalog) FetchConfig() error

func (*Catalog) FetchServices 

func (c *Catalog) FetchServices() error

FetchServices populates zones.

func (*Catalog) LastUpdated 

func (c *Catalog) LastUpdated() time.Time

LastUpdated returns the last time services changed.

func (*Catalog) Name 

func (c *Catalog) Name() string

Name implements plugin.Handler.

func (*Catalog) Ready 

func (c *Catalog) Ready() bool

Ready implements ready.Readiness.

func (*Catalog) ServeDNS 

func (c *Catalog) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg) (int, error)

ServeDNS implements plugin.Handler.

func (*Catalog) ServiceFor 

func (c *Catalog) ServiceFor(name string) (svc *Service)

func (*Catalog) Services 

func (c *Catalog) Services() map[string]*Service

Services returns a map of services to their target.

func (*Catalog) SetClients 

func (c *Catalog) SetClients(client ClientCatalog, kv KVClient)

SetClient sets a consul client for a catalog.

type ClientCatalog 

type ClientCatalog interface {
	Service(string, string, *api.QueryOptions) ([]*api.CatalogService, *api.QueryMeta, error)
	Services(*api.QueryOptions) (map[string][]string, *api.QueryMeta, error)
}

ClientCatalog is implemented by github.com/hashicorp/consul/api.Catalog.

type KVClient 

type KVClient interface {
	Get(string, *api.QueryOptions) (*api.KVPair, *api.QueryMeta, error)
}

KVClient is implemented by github.com/hashicorp/consul/api.Catalog.

type KVEntries 

type KVEntries struct {
	Target string
	ACL    []string
}

type Service 

type Service struct {
	Name      string
	Target    string
	ACL       []*ServiceACL
	Addresses []net.IP
	ApplyACL  bool
}

Service has a target and ACL rules.

func (Service) RespondsTo 

func (s Service) RespondsTo(ip net.IP) bool

RespondsTo returns if a service is allowed to talk to an IP.

type ServiceACL 

type ServiceACL struct {
	Action  string
	Network *net.IPNet
}

ServiceACL holds an action and corresponding network range.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.