sigs.k8s.io/external-dns@v0.14.1/docs/contributing/crd-source.md (about)

     1  # CRD Source
     2  
     3  CRD source provides a generic mechanism to manage DNS records in your favourite DNS provider supported by external-dns.
     4  
     5  ### Details
     6  
     7  CRD source watches for a user specified CRD to extract [Endpoints](https://github.com/kubernetes-sigs/external-dns/blob/HEAD/endpoint/endpoint.go) from its `Spec`.
     8  So users need to create such a CRD and register it to the kubernetes cluster and then create new object(s) of the CRD specifying the Endpoints.
     9  
    10  ### Registering CRD
    11  
    12  Here is typical example of [CRD API type](https://github.com/kubernetes-sigs/external-dns/blob/HEAD/endpoint/endpoint.go) which provides Endpoints to `CRD source`:
    13  
    14  ```go
    15  type TTL int64
    16  type Targets []string
    17  type ProviderSpecificProperty struct {
    18  	Name  string `json:"name,omitempty"`
    19  	Value string `json:"value,omitempty"`
    20  }
    21  type ProviderSpecific []ProviderSpecificProperty
    22  type Labels map[string]string
    23  
    24  type Endpoint struct {
    25  	// The hostname of the DNS record
    26  	DNSName string `json:"dnsName,omitempty"`
    27  	// The targets the DNS record points to
    28  	Targets Targets `json:"targets,omitempty"`
    29  	// RecordType type of record, e.g. CNAME, A, SRV, TXT etc
    30  	RecordType string `json:"recordType,omitempty"`
    31  	// TTL for the record
    32  	RecordTTL TTL `json:"recordTTL,omitempty"`
    33  	// Labels stores labels defined for the Endpoint
    34  	// +optional
    35  	Labels Labels `json:"labels,omitempty"`
    36  	// ProviderSpecific stores provider specific config
    37  	// +optional
    38  	ProviderSpecific ProviderSpecific `json:"providerSpecific,omitempty"`
    39  }
    40  
    41  type DNSEndpointSpec struct {
    42  	Endpoints []*Endpoint `json:"endpoints,omitempty"`
    43  }
    44  
    45  type DNSEndpointStatus struct {
    46  	// The generation observed by the external-dns controller.
    47  	// +optional
    48  	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
    49  }
    50  
    51  // +genclient
    52  // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
    53  
    54  // DNSEndpoint is the CRD wrapper for Endpoint
    55  // +k8s:openapi-gen=true
    56  // +kubebuilder:resource:path=dnsendpoints
    57  // +kubebuilder:subresource:status
    58  type DNSEndpoint struct {
    59  	metav1.TypeMeta   `json:",inline"`
    60  	metav1.ObjectMeta `json:"metadata,omitempty"`
    61  
    62  	Spec   DNSEndpointSpec   `json:"spec,omitempty"`
    63  	Status DNSEndpointStatus `json:"status,omitempty"`
    64  }
    65  
    66  ```
    67  
    68  Refer to [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) to create and register the CRD.
    69  
    70  ### Usage
    71  
    72  One can use CRD source by specifying `--source` flag with `crd` and specifying the ApiVersion and Kind of the CRD with `--crd-source-apiversion` and `crd-source-kind` respectively.
    73  for e.g:
    74  
    75  ```
    76  $ build/external-dns --source crd --crd-source-apiversion externaldns.k8s.io/v1alpha1  --crd-source-kind DNSEndpoint --provider inmemory --once --dry-run
    77  ```
    78  
    79  ### Creating DNS Records
    80  
    81  Create the objects of CRD type by filling in the fields of CRD and DNS record would be created accordingly.
    82  
    83  ### Example
    84  
    85  Here is an example [CRD manifest](crd-source/crd-manifest.yaml) generated by kubebuilder.
    86  Apply this to register the CRD
    87  
    88  ```
    89  $ kubectl apply --validate=false -f docs/contributing/crd-source/crd-manifest.yaml
    90  customresourcedefinition.apiextensions.k8s.io "dnsendpoints.externaldns.k8s.io" created
    91  ```
    92  
    93  Then you can create the dns-endpoint yaml similar to [dnsendpoint-example](crd-source/dnsendpoint-example.yaml)
    94  
    95  ```
    96  $ kubectl apply -f docs/contributing/crd-source/dnsendpoint-example.yaml
    97  dnsendpoint.externaldns.k8s.io "examplednsrecord" created
    98  ```
    99  
   100  Run external-dns in dry-mode to see whether external-dns picks up the DNS record from CRD.
   101  
   102  ```
   103  $ build/external-dns --source crd --crd-source-apiversion externaldns.k8s.io/v1alpha1  --crd-source-kind DNSEndpoint --provider inmemory --once --dry-run
   104  INFO[0000] running in dry-run mode. No changes to DNS records will be made.
   105  INFO[0000] Connected to cluster at https://192.168.99.100:8443
   106  INFO[0000] CREATE: foo.bar.com 180 IN A 192.168.99.216
   107  INFO[0000] CREATE: foo.bar.com 0 IN TXT "heritage=external-dns,external-dns/owner=default"
   108  ```
   109  
   110  ### RBAC configuration
   111  
   112  If you use RBAC, extend the `external-dns` ClusterRole with:
   113  ```
   114  - apiGroups: ["externaldns.k8s.io"]
   115    resources: ["dnsendpoints"]
   116    verbs: ["get","watch","list"]
   117  - apiGroups: ["externaldns.k8s.io"]
   118    resources: ["dnsendpoints/status"]
   119    verbs: ["*"]
   120  ```