<commit_before># KEP-2551: kubectl exit code standardization

<!-- toc -->
- [Release Signoff Checklist](#release-signoff-checklist)
- [Summary](#summary)
- [Motivation](#motivation)
  - [Goals](#goals)
  - [Non-Goals](#non-goals)
- [Proposal](#proposal)
  - [User Stories (Optional)](#user-stories-optional)
    - [Story 1](#story-1)
    - [Story 2](#story-2)
    - [Story 3](#story-3)
  - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
  - [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
  - [Changing error checker functions](#changing-error-checker-functions)
  - [Creating new error parser functions](#creating-new-error-parser-functions)
  - [Hybrid approach](#hybrid-approach)
  - [Test Plan](#test-plan)
  - [Graduation Criteria](#graduation-criteria)
  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
  - [Version Skew Strategy](#version-skew-strategy)
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
  - [Feature Enablement and Rollback](#feature-enablement-and-rollback)
  - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning)
  - [Monitoring Requirements](#monitoring-requirements)
  - [Dependencies](#dependencies)
  - [Scalability](#scalability)
  - [Troubleshooting](#troubleshooting)
- [Implementation History](#implementation-history)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
<!-- /toc -->

## Release Signoff Checklist

Items marked with (R) are required *prior to targeting to a milestone / release*.

- [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
- [ ] (R) KEP approvers have approved the KEP status as `implementable`
- [ ] (R) Design details are appropriately documented
- [ ] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
- [ ] (R) Graduation criteria is in place
- [ ] (R) Production readiness review completed
- [ ] (R) Production readiness review approved
- [ ] "Implementation History" section is up-to-date for milestone
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes

<!--
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
-->

[kubernetes.io]: https://kubernetes.io/
[kubernetes/enhancements]: https://git.k8s.io/enhancements
[kubernetes/kubernetes]: https://git.k8s.io/kubernetes
[kubernetes/website]: https://git.k8s.io/website

## Summary

Standardize the exit codes of kubectl when the command is successful or when it fails

## Motivation

kubectl is composed of several commands and subcommands, that can deal only with functions
as simple as getting the current version of server and client, to more complex functions
as getting differences between a local file and the current created resource on a Kubernetes
cluster, or doing some deployment roll out.

Additionally, some of those commands may call other external system commands (like an editor, 
or a diff command, or even a plugin). 

This brings a complexity about assessing:
* Was the command executed correctly
* If not, where was the problem? On the server side? Was the certificate expired? Or the resource does not exists?
* Was that a problem on the client side? Was that a problem of an external system command?

We have a number of issues across the repo, as [kubernetes #99354](https://github.com/kubernetes/kubernetes/issues/99354),
[kubectl #847](https://github.com/kubernetes/kubectl/issues/847), 
[kubernetes #73056](https://github.com/kubernetes/kubernetes/issues/73056), 
[kubernetes #39767](https://github.com/kubernetes/kubernetes/issues/39767) and 
[kubernetes #26424](https://github.com/kubernetes/kubernetes/issues/26424) that points
to this specific problem.

### Goals

* Document possible exit codes for kubectl 
* Implement the exit code common return function (maybe as a util function) 
* Gradually implement the exit code standardization for each command  

### Non-Goals

* Define a different return for each internal kubectl step or each APIServer condition/return

## Proposal

* Define the majority of the behaviors that a kubectl request can face:
  * Possible errors on the client side.
  * Possible errors on the server side.
* Define a table/list of numeric error codes for each of the main cases:
  * If the error code is related to a subcommand (as diff), we might have a return code that is defined as "error on the external subcommand" (like 128) and sum with the exit code from the external command (so a 130 exit code means 128 + exit code of '2' from the external subcommand/plugin)
* Implement a common way so commands can delegate the exit code normalization to a different function

### User Stories (Optional)

#### Story 1
Joice, the SRE of a big company is automating the deployment of the infrastructure with a lot of kubectl commands.
Usually they use an external plugin to verify if the manifests are linted, and issue a warning if not. Joice wants to
safelly ignore those lint errors from the plugin on the pipeline, as the exit code for linting might be well known, but 
wants to warn users when the apply command fails because of differences between the manifests.

#### Story 2
<NAME>, the security administrator of the Gotham Inc Company is following the development of a new product. Bruce asked
for the developers to warn when a new deployment fails because of the lack of some permission, so those permissions can be 
updated for the pipeline to work correctly.

The developers are making a lot of changes, and they keeps asking for Bruce to look for every pipeline execution, even those that 
fails because of wrong manifests and not because of authorization issues. So Bruce needs a new mechanism: That the pipeline knows
when it fails because of the lack of the authorization on Kubernetes API Server, and then the warning is sent to the security team
only when the pipeline breaks because of a specific error code that represents this authorization failure.

#### Story 3
Roberta works as the product manager of a big CI/CD SaaS provider. They want to have in their marketplace the
execution of kubernetes commands targeting a cluster, and fastly providing a feedback to the user if the error
was due to something on the client side (like a missing flag, an invalid yaml file because of...tabs...) or if this
is due to some invalid operation on the server side.


### Notes/Constraints/Caveats (Optional)

<!--
What are the caveats to the proposal?<commit_msg>Add a note that impl needs to check max error code<commit_after># KEP-2551: kubectl exit code standardization

<!-- toc -->
- [Release Signoff Checklist](#release-signoff-checklist)
- [Summary](#summary)
- [Motivation](#motivation)
  - [Goals](#goals)
  - [Non-Goals](#non-goals)
- [Proposal](#proposal)
  - [User Stories (Optional)](#user-stories-optional)
    - [Story 1](#story-1)
    - [Story 2](#story-2)
    - [Story 3](#story-3)
  - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional)
  - [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
  - [Changing error checker functions](#changing-error-checker-functions)
  - [Creating new error parser functions](#creating-new-error-parser-functions)
  - [Hybrid approach](#hybrid-approach)
  - [Test Plan](#test-plan)
  - [Graduation Criteria](#graduation-criteria)
  - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy)
  - [Version Skew Strategy](#version-skew-strategy)
- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire)
  - [Feature Enablement and Rollback](#feature-enablement-and-rollback)
  - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning)
  - [Monitoring Requirements](#monitoring-requirements)
  - [Dependencies](#dependencies)
  - [Scalability](#scalability)
  - [Troubleshooting](#troubleshooting)
- [Implementation History](#implementation-history)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
- [Infrastructure Needed (Optional)](#infrastructure-needed-optional)
<!-- /toc -->

## Release Signoff Checklist

Items marked with (R) are required *prior to targeting to a milestone / release*.

- [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR)
- [ ] (R) KEP approvers have approved the KEP status as `implementable`
- [ ] (R) Design details are appropriately documented
- [ ] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors)
- [ ] (R) Graduation criteria is in place
- [ ] (R) Production readiness review completed
- [ ] (R) Production readiness review approved
- [ ] "Implementation History" section is up-to-date for milestone
- [ ] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io]
- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes

<!--
**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone.
-->

[kubernetes.io]: https://kubernetes.io/
[kubernetes/enhancements]: https://git.k8s.io/enhancements
[kubernetes/kubernetes]: https://git.k8s.io/kubernetes
[kubernetes/website]: https://git.k8s.io/website

## Summary

Standardize the exit codes of kubectl when the command is successful or when it fails

## Motivation

kubectl is composed of several commands and subcommands, that can deal only with functions
as simple as getting the current version of server and client, to more complex functions
as getting differences between a local file and the current created resource on a Kubernetes
cluster, or doing some deployment roll out.

Additionally, some of those commands may call other external system commands (like an editor, 
or a diff command, or even a plugin). 

This brings a complexity about assessing:
* Was the command executed correctly
* If not, where was the problem? On the server side? Was the certificate expired? Or the resource does not exists?
* Was that a problem on the client side? Was that a problem of an external system command?

We have a number of issues across the repo, as [kubernetes #99354](https://github.com/kubernetes/kubernetes/issues/99354),
[kubectl #847](https://github.com/kubernetes/kubectl/issues/847), 
[kubernetes #73056](https://github.com/kubernetes/kubernetes/issues/73056), 
[kubernetes #39767](https://github.com/kubernetes/kubernetes/issues/39767) and 
[kubernetes #26424](https://github.com/kubernetes/kubernetes/issues/26424) that points
to this specific problem.

### Goals

* Document possible exit codes for kubectl 
* Implement the exit code common return function (maybe as a util function) 
* Gradually implement the exit code standardization for each command  

### Non-Goals

* Define a different return for each internal kubectl step or each APIServer condition/return

## Proposal

* Define the majority of the behaviors that a kubectl request can face:
  * Possible errors on the client side.
  * Possible errors on the server side.
* Define a table/list of numeric error codes for each of the main cases:
  * If the error code is related to a subcommand (as diff), we might have a return code that is defined as "error on the external subcommand" (like 128) and sum with the exit code from the external command (so a 130 exit code means 128 + exit code of '2' from the external subcommand/plugin). The code MUST VERIFY if the sum is not bigger than 255 and if it is 
  correct the value instead of leaving this for a panic.
* Implement a common way so commands can delegate the exit code normalization to a different function

### User Stories (Optional)

#### Story 1
Joice, the SRE of a big company is automating the deployment of the infrastructure with a lot of kubectl commands.
Usually they use an external plugin to verify if the manifests are linted, and issue a warning if not. Joice wants to
safelly ignore those lint errors from the plugin on the pipeline, as the exit code for linting might be well known, but 
wants to warn users when the apply command fails because of differences between the manifests.

#### Story 2
<NAME>, the security administrator of the Gotham Inc Company is following the development of a new product. Bruce asked
for the developers to warn when a new deployment fails because of the lack of some permission, so those permissions can be 
updated for the pipeline to work correctly.

The developers are making a lot of changes, and they keeps asking for Bruce to look for every pipeline execution, even those that 
fails because of wrong manifests and not because of authorization issues. So Bruce needs a new mechanism: That the pipeline knows
when it fails because of the lack of the authorization on Kubernetes API Server, and then the warning is sent to the security team
only when the pipeline breaks because of a specific error code that represents this authorization failure.

#### Story 3
Roberta works as the product manager of a big CI/CD SaaS provider. They want to have in their marketplace the
execution of kubernetes commands targeting a cluster, and fastly providing a feedback to the user if the error
was due to something on the client side (like a missing flag, an invalid yaml file because of...tabs...) or if this
is due to some invalid operation on the server side.


### Notes/Constraints/Caveats (Optional)

<!--
What are the caveats to the proposal?
{'fraction_non_alphanumeric': 0.084740910392213, 'fraction_numerical': 0.010521042084168337, 'mean_word_length': 4.616157556270096, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 11, 'https://': 18, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3397060', 'n_tokens_mistral': 3938, 'n_tokens_neox': 3582, 'n_words': 1707}