{"id":14975817,"url":"https://github.com/mia-platform/jpl","last_synced_at":"2025-07-18T06:35:46.530Z","repository":{"id":60986885,"uuid":"534653827","full_name":"mia-platform/jpl","owner":"mia-platform","description":"jpl provides the functions used for connecting and applying manifests files to a kubernetes cluster","archived":false,"fork":false,"pushed_at":"2025-06-03T08:28:49.000Z","size":444,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-03T19:37:06.370Z","etag":null,"topics":["golang","kubernetes","library"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mia-platform.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-09-09T13:27:10.000Z","updated_at":"2025-06-03T08:28:51.000Z","dependencies_parsed_at":"2023-02-10T11:01:12.121Z","dependency_job_id":"a6a0eeda-796a-4542-bfe4-95eaa1d58373","html_url":"https://github.com/mia-platform/jpl","commit_stats":{"total_commits":116,"total_committers":4,"mean_commits":29.0,"dds":0.3879310344827587,"last_synced_commit":"4dac848b38f6cd3d44262baf3e582c8dce57fbf8"},"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/mia-platform/jpl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fjpl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fjpl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fjpl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fjpl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mia-platform","download_url":"https://codeload.github.com/mia-platform/jpl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mia-platform%2Fjpl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265711068,"owners_count":23815466,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golang","kubernetes","library"],"created_at":"2024-09-24T13:52:41.996Z","updated_at":"2025-07-18T06:35:46.490Z","avatar_url":"https://github.com/mia-platform.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jpl\n\n[![Go Report Card][go-report-card]][go-report-card-link]\n[![Go Package Reference Site][go-package-svg]][go-package-link]\n\n`JPL` is a library to simplify the application of a series of kuberntes resources saved on files to a remote cluster.  \nIt also add some nice to have features that lacks in kubectl:\n\n- resources ordering\n- automatic waiting of current statuses\n- generating new resources from manifests\n- check if flowcontrol api is enabled on the remote cluster\n- keep inventory of applied resoruces for automatic pruning\n\nThe fastest way to add this library to a project is to run `go get github.com/mia-platform/jpl@latest` with go1.16+\n\n## Table of Contents\n\n- [What's included](#whats-included)\n- [Features](#features)\n- [Compatibility: jpl \u003c-\u003e Kubernetes clusters](#compatibility-jpl---kubernetes-clusters)\n  - [Compatibility matrix](#compatibility-matrix)\n- [How to get it](#how-to-get-it)\n\n### What's included\n\n- the `client` package contains the client to apply the resources to a Kubernetes API server\n- the `event` package contains the various events that the `client` will return to tell the user what is happening\n- the `filter` package contain a filter interface for omit resources from the current apply action\n- the `flowcontrol` package contains the checks necessary to know if the Kubernetes API server has the flowcontrol enabled\n- the `generator` package contain built-in generators that can be used to generate new resources from other manifests\n- the `inventory` package is used to keep track of the resources deployed in precedent apply to compute the\n\tnecessary pruning actions\n- the `mutator` package contain built-in mutators that can be used to modify resources before applying them\n- the `resource` package contains useful utils function to work with Unstructured data\n- the `resourcereader` package is useful for parsing valid kubernetes resource manifests from a folder of yaml file\n\tor via stdin\n- the `runner` package contains a queue like executor of a series of tasks sequentially\n- the `testing` package contains utils for testing the other packages\n- the `util` package contains utility resources\n\n### Features\n\n#### Pruning\n\nThe Applier automatically deletes objects that were previously applied and then removed from the input set on\na subsequent apply.\n\nThe current implementation of `kubectl apply --prune` is an alpha, and it is improbable that it will graduate to beta.\n`jpl` attempts to address the current deficiencies by storing the set of previously applied objects in an **inventory**\nobject which is applied to the cluster. The reference implementation uses a `ConfigMap` as an **inventory** object\nand references to the applied objects are stored in the `data` section of the `ConfigMap` that is generated and\nrecovered at every run.\n\n#### Waiting for Reconciliation\n\nThe Applier automatically watches applied objects and tracks their status, blocking until the objects have reconciled\nor failed.\n\nThis functionality is similar to `kubectl delete \u003cresource\u003e \u003cname\u003e --wait`, in that it waits for all finalizers\nto complete, except it works for creates and updates.\n\nWhile there is a `kubectl apply \u003cresource\u003e \u003cname\u003e --wait`, it only waits for deletes when combined with `--prune`.\n`jpl` provides an alternative that works for all spec changes, waiting for reconciliation, the convergence of\nstatus to the desired specification. After reconciliation, it is expected that the object has reached a steady state\nuntil the specification is changed again.\n\n#### Resource Ordering\n\nThe Applier use resource type to determine which order to apply and delete objects.\n\nIn contrast, when using `kubectl apply`, the objects are applied in alphanumeric order of their file names,\nand top to bottom in each file. With `jpl`, this manual sorting is unnecessary for many common use cases.\n\n##### Implicit Dependency Ordering\n\n`jpl` automatically detects some implicit dependencies that includes:\n\n1. Namespace-scoped resource objects depend on their Namespace\n1. Custom resource objects depend on their Custom Resource Definition\n1. Validation and Mutating Webhooks depends on their Services\n\nLike resource ordering, implicit dependency ordering improves the apply and delete experience to reduce the need to\nmanually specify ordering for many common use cases. This allows more objects to be applied together all at once,\nwith less manual orchestration.\n\n##### Explicit Dependency Ordering\n\nIn addition to implicit dependencies sometimes the user would like to determine certain resources ordering.\nIn these cases, the user can use explicit dependency ordering by adding a\n`config.kubernetes.io/depends-on: \u003cOBJECT_REFERENCE\u003e` annotation to an object.\n\nThe Applier use these explicit dependency directives to build a dependency tree and flatten it for determining apply\nordering.\n\nIn addition to ordering the applies, dependency ordering also waits for dependency reconciliation when applying.\nThis ensures that dependencies are not just applied first, but have reconciled before their dependents are applied.\n\nIn the following example, the `config.kubernetes.io/depends-on` annotation identifies that `nginx` must be successfully\napplied prior to `workload` actuation:\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: workload\n  annotations:\n    config.kubernetes.io/depends-on: /namespaces/default/Pod/nginx\nspec:\n  containers:\n    - name: workload\n      image: registry.k8s.io/pause:2.0\n```\n\n### Compatibility: jpl \u003c-\u003e Kubernetes clusters\n\nSince `jpl` will use the Kuberntes packages to execute calls, every version of the library is compatible with\nthe versions of Kubernetes that are compatible with them.\n\n#### Compatibility matrix\n\n|             | Kubernetes 1.27 | Kubernetes 1.28 | Kubernetes 1.29 | Kubernetes 1.30 | Kubernetes 1.31 | Kubernetes 1.32 |\n| ------------| --------------- | --------------- | --------------- | --------------- | --------------- | --------------- |\n| `jpl-0.2.x` | +-              | ✓               | +-              | +-              | +-              | +-              |\n| `jpl-0.3.x` | +-              | ✓               | +-              | +-              | +-              | +-              |\n| `jpl-0.5.x` | +-              | +-              | +-              | ✓               | +-              | +-              |\n| `jpl-0.6.x` | +-              | +-              | +-              | +-              | ✓               | +-              |\n| `HEAD`      | +-              | +-              | +-              | +-              | ✓               | +-              |\n\nKey:\n\n- `✓` the Kubernetes version officially sypported by the packages versions\n- `+` kubernetes packages can have features or API objects that may not be present in the Kubernetes cluster,\n\teither due to that client-go has additional new API, or that the server has removed old API. However,\n\teverything they have in common (i.e., most APIs) will work. Please note that alpha APIs may vanish\n\tor change significantly in a single release.\n- `-` The Kubernetes cluster has features that the kubernetes packages can't use, either due to the server has\n\tadditional new API, or that client-go has removed old API. However, everything they share in common\n\t(i.e., most APIs) will work.\n\nSee the [CHANGELOG](./CHANGELOG.md) for a detailed description of changes between jpl versions.\n\n### How to get it\n\nTo get the latest version, use go1.16+ and fetch using the `go get` command. For example:\n\n```sh\ngo get github.com/mia-platform/jpl@latest\n```\n\nTo get a specific version, use go1.11+ and fetch the desired version using the `go get` command. For example:\n\n```sh\ngo get github.com/mia-platform/jpl@v0.2.0\n```\n\n[go-report-card]: https://goreportcard.com/badge/github.com/mia-platform/jpl\n[go-report-card-link]: https://goreportcard.com/report/github.com/mia-platform/jpl\n[go-package-link]: https://pkg.go.dev/github.com/mia-platform/jpl\n[go-package-svg]: https://pkg.go.dev/badge/github.com/mia-platform/jpl.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmia-platform%2Fjpl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmia-platform%2Fjpl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmia-platform%2Fjpl/lists"}