github.com/cilium/cilium@v1.16.2/pkg/k8s/slim/README.md (about)

     1  # Slim Kubernetes structures
     2  
     3  This package is intended to be a slim copy of the structures used in k8s watchers.
     4  
     5  The most common structures are under `vendor/k8s.io/api/core/v1/types.go`, or
     6  `vendor/k8s.io/apimachinery/pkg/apis/meta/v1/types.go`.
     7  
     8  Use the following script to update the slim files. Update the `tag` variable as
     9  necessary. Keep in mind that updating the slim files is not as simple as
    10  accepting the changes that the script generates. Only the changes relevant to
    11  the structures used by Cilium are necessary to keep.
    12  
    13  Note: if updating from RC versions, first run the script as-is and commit in a
    14  temporary commit all of the changes generated by the script. Then, update the
    15  `tag` and re-run the script. Any changes to the slim structures in the
    16  generated diff is what needs to be committed; all other changes are
    17  unnecessary.
    18  
    19  ```bash
    20  tag=v1.29.0-rc.1
    21  url="https://raw.githubusercontent.com/kubernetes/kubernetes/${tag}"
    22  
    23  curl "${url}/staging/src/k8s.io/api/core/v1/doc.go" > pkg/k8s/slim/k8s/api/core/v1/doc.go
    24  curl "${url}/staging/src/k8s.io/api/core/v1/register.go" > pkg/k8s/slim/k8s/api/core/v1/register.go
    25  curl "${url}/staging/src/k8s.io/api/core/v1/taint.go" > pkg/k8s/slim/k8s/api/core/v1/taint.go
    26  curl "${url}/staging/src/k8s.io/api/core/v1/types.go" > pkg/k8s/slim/k8s/api/core/v1/types.go
    27  
    28  curl "${url}/staging/src/k8s.io/api/discovery/v1beta1/doc.go" > pkg/k8s/slim/k8s/api/discovery/v1beta1/doc.go
    29  curl "${url}/staging/src/k8s.io/api/discovery/v1beta1/register.go" > pkg/k8s/slim/k8s/api/discovery/v1beta1/register.go
    30  curl "${url}/staging/src/k8s.io/api/discovery/v1beta1/types.go" > pkg/k8s/slim/k8s/api/discovery/v1beta1/types.go
    31  curl "${url}/staging/src/k8s.io/api/discovery/v1beta1/well_known_labels.go" > pkg/k8s/slim/k8s/api/discovery/v1beta1/well_known_labels.go
    32  
    33  curl "${url}/staging/src/k8s.io/api/discovery/v1/doc.go" > pkg/k8s/slim/k8s/api/discovery/v1/doc.go
    34  curl "${url}/staging/src/k8s.io/api/discovery/v1/register.go" > pkg/k8s/slim/k8s/api/discovery/v1/register.go
    35  curl "${url}/staging/src/k8s.io/api/discovery/v1/types.go" > pkg/k8s/slim/k8s/api/discovery/v1/types.go
    36  curl "${url}/staging/src/k8s.io/api/discovery/v1/well_known_labels.go" > pkg/k8s/slim/k8s/api/discovery/v1/well_known_labels.go
    37  
    38  curl "${url}/staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1/doc.go" > pkg/k8s/slim/k8s/apis/apiextensions/v1/doc.go
    39  curl "${url}/staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1/register.go" > pkg/k8s/slim/k8s/apis/apiextensions/v1/register.go
    40  curl "${url}/staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1/types.go" > pkg/k8s/slim/k8s/apis/apiextensions/v1/types.go
    41  
    42  curl "${url}/staging/src/k8s.io/apimachinery/pkg/labels/doc.go" > pkg/k8s/slim/k8s/apis/labels/doc.go
    43  curl "${url}/staging/src/k8s.io/apimachinery/pkg/labels/labels.go" > pkg/k8s/slim/k8s/apis/labels/labels.go
    44  curl "${url}/staging/src/k8s.io/apimachinery/pkg/labels/selector.go" > pkg/k8s/slim/k8s/apis/labels/selector.go
    45  
    46  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/validation/validation.go" > pkg/k8s/slim/k8s/apis/meta/v1/validation/validation.go
    47  
    48  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/doc.go" > pkg/k8s/slim/k8s/apis/meta/v1/doc.go
    49  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/helpers.go" > pkg/k8s/slim/k8s/apis/meta/v1/helpers.go
    50  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/meta.go" > pkg/k8s/slim/k8s/apis/meta/v1/meta.go
    51  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/register.go" > pkg/k8s/slim/k8s/apis/meta/v1/register.go
    52  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/time.go" > pkg/k8s/slim/k8s/apis/meta/v1/time.go
    53  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/time_proto.go" > pkg/k8s/slim/k8s/apis/meta/v1/time_proto.go
    54  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1/types.go" > pkg/k8s/slim/k8s/apis/meta/v1/types.go
    55  
    56  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1beta1/doc.go" > pkg/k8s/slim/k8s/apis/meta/v1beta1/doc.go
    57  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1beta1/register.go" > pkg/k8s/slim/k8s/apis/meta/v1beta1/register.go
    58  curl "${url}/staging/src/k8s.io/apimachinery/pkg/apis/meta/v1beta1/types.go" > pkg/k8s/slim/k8s/apis/meta/v1beta1/types.go
    59  
    60  curl "${url}/staging/src/k8s.io/api/networking/v1/doc.go" > pkg/k8s/slim/k8s/api/networking/v1/doc.go
    61  curl "${url}/staging/src/k8s.io/api/networking/v1/register.go" > pkg/k8s/slim/k8s/api/networking/v1/register.go
    62  curl "${url}/staging/src/k8s.io/api/networking/v1/types.go" > pkg/k8s/slim/k8s/api/networking/v1/types.go
    63  curl "${url}/staging/src/k8s.io/api/networking/v1/well_known_annotations.go" > pkg/k8s/slim/k8s/api/networking/v1/well_known_annotations.go
    64  
    65  curl "${url}/staging/src/k8s.io/apimachinery/pkg/selection/operator.go" > pkg/k8s/slim/k8s/apis/selection/operator.go
    66  
    67  curl "${url}/staging/src/k8s.io/apimachinery/pkg/util/intstr/intstr.go" > pkg/k8s/slim/k8s/apis/util/intstr/intstr.go
    68  
    69  curl "${url}/staging/src/k8s.io/apimachinery/pkg/api/meta/conditions.go" > pkg/k8s/slim/k8s/apis/api/meta/conditions.go
    70  ```
    71  
    72  All fields of the copied structures are exactly the same as the ones available
    73  in the official k8s source code. To keep a slimmer version of these structures
    74  make sure the unused fields by Cilium are removed from the slimmer versions.
    75  See below section regarding gotchas.
    76  
    77  If new fields need to be added or removed to these structures, some files need
    78  to be regenerated with `make generate-k8s-api` in the root directory of this
    79  repository.
    80  
    81  The directory `./k8s/client` is entirely auto-generated. This directory has the
    82  source code of an optimized Kubernetes client.
    83  
    84  With this optimized Kubernetes client we can wrap some official and
    85  non-optimized Kubernetes interfaces with the ones built for the slimmer
    86  versions. So make sure you are correctly wrapping the interfaces with our
    87  implementations. If this client is used a structure that is not registered under
    88  "register.go" of that package or if the client is being used for a type that is
    89  not optimized yet, you will hit the error:
    90  `Failed to list ... no kind "..." is registered for version "v1"`. To fix this
    91  make sure the package is registered and the client is supposed to be used
    92  for that structure.
    93  
    94  ## Gotchas for updating slim structures
    95  
    96  * Remove any changes regarding comments starting with "import ..." because that
    97    affects the protoc's code generation
    98  * Remove any changes regarding a change of the import path for the `core` and
    99    `meta` v1* packages, i.e. undo changes that cause the import path to fallback
   100    to "k8s.io/..." rather than "pkg/k8s/slim/..."
   101  * Remove all new structures that are not used by Cilium and only update the
   102    structures that are in use
   103  * Ignore all changes to `pkg/k8s/slim/k8s/apis/meta/v1/meta.go` regarding the
   104    `Object` interface methods, unless the updating you are performing requires
   105    these interface methods to change.
   106  * Ignore changes that remove that the `kubebuilder` directives on the
   107    `LabelSelectorRequirement` struct, especially for the `Operator` field.
   108  * Ignore changes to `LabelSelector` inside
   109    `pkg/k8s/slim/k8s/apis/meta/v1/types.go` and `MatchLabelsValue`. The latter
   110    is a custom type that we depend on.
   111  * Ignore changes inside `pkg/k8s/slim/k8s/apis/labels/selector.go` regarding
   112    new fields in the `Parser` struct, especially with `path`. If new fields are
   113    added to the struct, add them if you know what you are doing.