Updates to repo and rule documentation (#26)

This commit is contained in:
Bernie White 2020-01-02 15:31:15 +10:00 коммит произвёл GitHub
Родитель 7fc7048f7c
Коммит 1021649dde
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
15 изменённых файлов: 280 добавлений и 52 удалений

67
.markdownlint.json Normal file
Просмотреть файл

@ -0,0 +1,67 @@
{
"default": true,
"header-increment": true,
"first-header-h1": {
"level": 1
},
"header-style": {
"style": "atx"
},
"ul-style": {
"style": "dash"
},
"list-indent": true,
"ul-start-left": true,
"ul-indent": {
"indent": 2
},
"no-trailing-spaces": true,
"no-hard-tabs": true,
"no-reversed-links": true,
"no-multiple-blanks": true,
"line-length": {
"line_length": 100,
"code_blocks": false,
"tables": false,
"headers": true
},
"commands-show-output": true,
"no-missing-space-atx": true,
"no-multiple-space-atx": true,
"no-missing-space-closed-atx": true,
"no-multiple-space-closed-atx": true,
"blanks-around-headers": true,
"header-start-left": true,
"no-duplicate-header": true,
"single-h1": true,
"no-trailing-punctuation": {
"punctuation": ".,;:!"
},
"no-multiple-space-blockquote": true,
"no-blanks-blockquote": true,
"ol-prefix": {
"style": "one_or_ordered"
},
"list-marker-space": true,
"blanks-around-fences": true,
"blanks-around-lists": true,
"no-bare-urls": true,
"hr-style": {
"style": "---"
},
"no-emphasis-as-header": true,
"no-space-in-emphasis": true,
"no-space-in-code": true,
"no-space-in-links": true,
"fenced-code-language": false,
"first-line-h1": false,
"no-empty-links": true,
"proper-names": {
"names": [
"PowerShell",
"JavaScript"
],
"code_blocks": false
},
"no-alt-text": true
}

3
.vscode/settings.json поставляемый
Просмотреть файл

@ -18,7 +18,8 @@
"**/.azure-pipelines/*.yaml": "azure-pipelines"
},
"cSpell.words": [
"Kubernetes"
"Kubernetes",
"setuid"
],
"cSpell.enabledLanguageIds": [
"csharp",

114
README.md
Просмотреть файл

@ -10,11 +10,11 @@ This project is to be considered a **proof-of-concept** and **not a supported pr
For issues with rules and documentation please check our GitHub [issues](https://github.com/BernieWhite/PSRule.Rules.Kubernetes/issues) page. If you do not see your problem captured, please file a new issue and follow the provided template.
If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/BernieWhite/PSRule/issues) page instead.
If you have any problems with the [PSRule][project] engine, please check the project GitHub [issues](https://github.com/Microsoft/PSRule/issues) page instead.
## Getting the modules
This project requires the PowerShell module PSRule.
This project requires the `PSRule` PowerShell module.
You can download and install these modules from the PowerShell Gallery.
@ -24,25 +24,123 @@ PSRule.Rules.Kubernetes | Validate Kubernetes resources | [latest][module] / [in
## Getting started
PSRule for Kubernetes provides two methods for analyzing Kubernetes resources:
- _Pre-flight_ - Before resources are deployed from a YAML manifest file.
- _In-flight_ - After resources are deployed to a Kubernetes cluster.
### Offline with a manifest
Kubernetes resources can be evaluated within a YAML manifest file.
Kubernetes resources can be validated within a YAML manifest file.
To validate Kubernetes resources use the `Invoke-PSRule` cmdlet. PSRule natively supports reading objects from YAML files using the `-InputPath` parameter.
The `-InputPath` parameter can be abbreviated to `-f`.
For example:
```powershell
Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputPath .\service.yaml;
Invoke-PSRule -f service.yaml -Module PSRule.Rules.Kubernetes;
```
The input path can be also be a URL to a YAML file. For example:
```powershell
$sourceUrl = 'https://raw.githubusercontent.com/Azure-Samples/azure-voting-app-redis/master/azure-vote-all-in-one-redis.yaml';
Invoke-PSRule -f $sourceUrl -Module PSRule.Rules.Kubernetes;
```
The output of this example is:
```text
TargetName: azure-vote-back
RuleName Outcome Recommendation
-------- ------- --------------
Kubernetes.API.Removal Fail Consider updating resource deployments to use newer API endpoints prior…
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
Kubernetes.Pod.PrivilegeEscalation Fail Containers should deny privilege escalation.
Kubernetes.Pod.Latest Fail Deployments or pods should identify a specific tag to use for container…
Kubernetes.Pod.Resources Fail Resource requirements are set for each container.
Kubernetes.Pod.Secrets Pass Use Kubernetes secrets to store information such as passwords or connec…
Kubernetes.Pod.Health Fail Containers should use liveness and readiness probes.
Kubernetes.Pod.Replicas Fail Consider increasing replicas to two or more to provide high availabilit…
Kubernetes.AKS.PublicLB Pass Consider creating services with an internal load balancer instead of a …
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
TargetName: azure-vote-front
RuleName Outcome Recommendation
-------- ------- --------------
Kubernetes.API.Removal Fail Consider updating resource deployments to use newer API endpoints prior…
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
Kubernetes.Pod.PrivilegeEscalation Fail Containers should deny privilege escalation.
Kubernetes.Pod.Latest Pass Deployments or pods should identify a specific tag to use for container…
Kubernetes.Pod.Resources Fail Resource requirements are set for each container.
Kubernetes.Pod.Secrets Pass Use Kubernetes secrets to store information such as passwords or connec…
Kubernetes.Pod.Health Fail Containers should use liveness and readiness probes.
Kubernetes.Pod.Replicas Fail Consider increasing replicas to two or more to provide high availabilit…
Kubernetes.AKS.PublicLB Fail Consider creating services with an internal load balancer instead of a …
Kubernetes.Metadata Fail Consider applying recommended labels defined by Kubernetes.…
```
### Online with kubectl
Kubernetes resources can be validated directly from a cluster using the output from `kubectl`.
To validate resources using `kubectl`, return the output as YAML with the `-o yaml` parameter.
For example:
```powershell
Invoke-PSRule -Module PSRule.Rules.Kubernetes -InputObject (kubectl get services -o yaml | Out-String) -Format Yaml -ObjectPath items;
kubectl get services -o yaml | Out-String | Invoke-PSRule -Format Yaml -ObjectPath items -Module PSRule.Rules.Kubernetes;
```
In the example above:
- `Out-String` - is used to concatenate the output into a single string object.
- `-Format Yaml` - indicates that the input is YAML.
- `-ObjectPath items` - indicates that the input nests objects to evaluate under the `items` property.
### Additional options
To filter results to only failed rules, use `Invoke-PSRule -Outcome Fail`.
Passed, failed and error results are shown by default.
For example:
```powershell
# Only show failed results
Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -Outcome Fail;
```
A summary of results can be displayed by using `Invoke-PSRule -As Summary`.
For example:
```powershell
# Display as summary results
Invoke-PSRule -f $sourceUrl -Module 'PSRule.Rules.Kubernetes' -As Summary;
```
The output of this example is:
```text
RuleName Pass Fail Outcome
-------- ---- ---- -------
Kubernetes.AKS.PublicLB 1 1 Fail
Kubernetes.API.Removal 0 2 Fail
Kubernetes.Metadata 0 4 Fail
Kubernetes.Pod.PrivilegeEscalation 0 2 Fail
Kubernetes.Pod.Latest 1 1 Fail
Kubernetes.Pod.Resources 0 2 Fail
Kubernetes.Pod.Secrets 2 0 Pass
Kubernetes.Pod.Health 0 2 Fail
Kubernetes.Pod.Replicas 0 2 Fail
```
## Rule reference
The following rules are included in the `PSRule.Rules.Kubernetes` module:
For a list of rules included in the `PSRule.Rules.Kubernetes` module see:
- [PSRule.Rules.Kubernetes](docs/rules/en-US/module.md)
- [Module rule reference](docs/rules/en-US/module.md)
## Changes and versioning
@ -61,4 +159,4 @@ This project is [licensed under the MIT License](LICENSE).
[install]: docs/scenarios/install-instructions.md
[ci-badge]: https://dev.azure.com/bewhite/PSRule.Rules.Kubernetes/_apis/build/status/PSRule.Rules.Kubernetes-CI?branchName=master
[module]: https://www.powershellgallery.com/packages/PSRule.Rules.Kubernetes
[project]: https://github.com/BernieWhite/PSRule
[project]: https://github.com/Microsoft/PSRule

Просмотреть файл

@ -1,21 +1,31 @@
Document 'module' {
Title 'Module rules'
Title 'Module rule reference'
Import-Module .\out\modules\PSRule.Rules.Kubernetes
$rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue
$rules = Get-PSRule -Module PSRule.Rules.Kubernetes -WarningAction SilentlyContinue |
Add-Member -MemberType ScriptProperty -Name Category -Value { $this.Info.Annotations.category } -PassThru |
Sort-Object -Property Category;
Section 'Baselines' {
# 'The following baselines are included in `PSRule.Rules.Kubernetes`.'
# 'The following baselines are included within `PSRule.Rules.Kubernetes`.'
}
Section 'Rules' {
'The following rules are included in `PSRule.Rules.Kubernetes`.'
'The following rules are included within `PSRule.Rules.Kubernetes`.'
$rules | Table -Property @{ Name = 'RuleName'; Expression = {
"[$($_.RuleName)]($($_.RuleName).md)"
}}, Description, @{ Name = 'Category'; Expression = {
$_.Tag.category
}}
$categories = $rules | Group-Object -Property Category;
foreach ($category in $categories) {
Section "$($category.Name)" {
$category.Group |
Sort-Object -Property RuleName |
Table -Property @{ Name = 'Name'; Expression = {
"[$($_.RuleName)]($($_.RuleName).md)"
}}, Synopsis, @{ Name = 'Severity'; Expression = {
$_.Info.Annotations.severity
}}
}
}
}
}

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Critical
category: Service exposure
category: Security
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.AKS.PublicLB.md
---
@ -21,3 +21,7 @@ When this annotation is used on a load balanced service, the Azure load balancer
## RECOMMENDATION
Consider creating services with an internal load balancer instead of a public load balancer.
## LINKS
- [Use an internal load balancer with Azure Kubernetes Service (AKS)](https://docs.microsoft.com/en-us/azure/aks/internal-lb#create-an-internal-load-balancer)

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Important
category: Resource APIs
category: API
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.API.Removal.md
---

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Important
category: Resource management
severity: Awareness
category: Management
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Metadata.md
---
@ -19,4 +19,6 @@ These labels should be used to consistently apply standard metadata.
Consider applying recommended labels defined by Kubernetes.
For more information see [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/).
## LINKS
- [Recommended Labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/)

Просмотреть файл

@ -1,5 +1,6 @@
---
severity: Important
category: Reliability
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Health.md
---
@ -17,7 +18,7 @@ This is accomplished through liveness and readiness probes.
## RECOMMENDATION
Containers should use liveness and readiness probes.
Consider configuring liveness and readiness probes for pod containers.
## LINKS

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Critical
category: Pod security
severity: Important
category: Security
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Latest.md
---
@ -19,6 +19,6 @@ Containers should use specific tags instead of latest.
Deployments or pods should identify a specific tag to use for container images instead of latest.
When latest is used it may be hard to determine which version of the image is running.
When using variable tags such as v1.0 (which may refer to v1.0.0 or v1.0.1) consider using imagePullPolicy: Always to ensure that the an out-of-date cached image is not used.
When using variable tags such as v1.0 (which may refer to v1.0.0 or v1.0.1) consider using `imagePullPolicy: Always` to ensure that the an out-of-date cached image is not used.
The latest tag automatically uses imagePullPolicy: Always instead of the default imagePullPolicy: IfNotPresent.
The latest tag automatically uses `imagePullPolicy: Always` instead of the default `imagePullPolicy: IfNotPresent`.

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Critical
category: Pod security
category: Security
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.PriviledgeEscalation.md
---
@ -12,8 +12,16 @@ Containers should deny privilege escalation.
## DESCRIPTION
Containers should deny privilege escalation.
In the default configuration, container processes are permitted to change the effective user ID through the _setuid_ binary.
Changing the effective user ID could allow a malicious or vulnerable process to gain a higher level of permission then intended.
To prevent this, explicitly set the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
## RECOMMENDATION
Containers should deny privilege escalation.
Consider explicitly setting the `securityContext.allowPrivilegeEscalation` option to `false` on pod containers.
## LINKS
- [Secure container access to resources](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-cluster-security#secure-container-access-to-resources)
- [Set the security context for a Container](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container)
- [Privilege Escalation](https://kubernetes.io/docs/concepts/policy/pod-security-policy/#privilege-escalation)

Просмотреть файл

@ -1,5 +1,6 @@
---
severity: Important
category: Reliability
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Replicas.md
---

Просмотреть файл

@ -1,19 +1,32 @@
---
severity: Important
category: Resource management
category: Performance
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Resources.md
---
# Set requirements for resources
# Set compute resource requirements
## SYNOPSIS
Resource requirements are set for each container.
Set CPU and memory requirements for each container.
## DESCRIPTION
Resource requirements are set for each container.
The default scheduler uses container compute resource configuration to select a node for scheduling the pod.
If compute resources values are not provided, Kubernetes can't take these into account when making scheduling decisions.
Compute resources is not the only factor to determine pod placement.
However, if the scheduler places a pod on a host with insufficient resources, pod performance may be impacted.
If the Kubernetes cluster uses resource quotas, pods that don't specify compute resources may be rejected.
Compute resources for a container are set within the pod specification by defining `requests` and `limits`.
## RECOMMENDATION
Resource requirements are set for each container.
Consider configuring CPU and memory resource requirements for each container.
## LINKS
- [Define pod resource requests and limits](https://docs.microsoft.com/en-us/azure/aks/developer-best-practices-resource-management#define-pod-resource-requests-and-limits)
- [Managing Compute Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#resource-types)

Просмотреть файл

@ -1,6 +1,6 @@
---
severity: Critical
category: Pod security
category: Security
online version: https://github.com/BernieWhite/PSRule.Rules.Kubernetes/blob/master/docs/rules/en-US/Kubernetes.Pod.Secrets.md
---

Просмотреть файл

@ -1,17 +1,39 @@
# Module rules
# Module rule reference
## Rules
The following rules are included in `PSRule.Rules.Kubernetes`.
The following rules are included within `PSRule.Rules.Kubernetes`.
RuleName | Description | Category
-------- | ----------- | --------
[Kubernetes.AKS.PublicLB](Kubernetes.AKS.PublicLB.md) | Use internal Azure load balancers. | Pod security
[Kubernetes.API.Removal](Kubernetes.API.Removal.md) | Avoid using legacy API endpoints. | API
[Kubernetes.Metadata](Kubernetes.Metadata.md) | Use Kubernetes common labels. | Resource management
[Kubernetes.Pod.PrivilegeEscalation](Kubernetes.Pod.PrivilegeEscalation.md) | Containers should deny privilege escalation. | Pod security
[Kubernetes.Pod.Latest](Kubernetes.Pod.Latest.md) | Containers should use specific tags instead of latest. | Pod security
[Kubernetes.Pod.Resources](Kubernetes.Pod.Resources.md) | Resource requirements are set for each container. | Resource management
[Kubernetes.Pod.Secrets](Kubernetes.Pod.Secrets.md) | Sensitive environment variables should be referenced as a secret. | Pod security
[Kubernetes.Pod.Health](Kubernetes.Pod.Health.md) | Containers should use liveness and readiness probes. | Reliability
[Kubernetes.Pod.Replicas](Kubernetes.Pod.Replicas.md) | Use two or more replicas. | Reliability
### API
Name | Synopsis | Severity
---- | -------- | --------
[Kubernetes.API.Removal](Kubernetes.API.Removal.md) | Avoid using legacy API endpoints. | Important
### Management
Name | Synopsis | Severity
---- | -------- | --------
[Kubernetes.Metadata](Kubernetes.Metadata.md) | Use Kubernetes common labels. | Awareness
### Performance
Name | Synopsis | Severity
---- | -------- | --------
[Kubernetes.Pod.Resources](Kubernetes.Pod.Resources.md) | Set CPU and memory requirements for each container. | Important
### Reliability
Name | Synopsis | Severity
---- | -------- | --------
[Kubernetes.Pod.Health](Kubernetes.Pod.Health.md) | Containers should use liveness and readiness probes. | Important
[Kubernetes.Pod.Replicas](Kubernetes.Pod.Replicas.md) | Use two or more replicas. | Important
### Security
Name | Synopsis | Severity
---- | -------- | --------
[Kubernetes.AKS.PublicLB](Kubernetes.AKS.PublicLB.md) | Use internal Azure load balancers. | Critical
[Kubernetes.Pod.Latest](Kubernetes.Pod.Latest.md) | Containers should use specific tags instead of latest. | Important
[Kubernetes.Pod.PrivilegeEscalation](Kubernetes.Pod.PrivilegeEscalation.md) | Containers should deny privilege escalation. | Critical
[Kubernetes.Pod.Secrets](Kubernetes.Pod.Secrets.md) | Sensitive environment variables should be referenced as a secret. | Critical

Просмотреть файл

@ -3,7 +3,7 @@
## Prerequisites
- Windows PowerShell 5.1 with .NET Framework 4.7.2+ or
- PowerShell Core 6.0 or greater on Windows, macOS and Linux
- PowerShell Core 6.2 or greater on Windows, MacOS and Linux
For a list of platforms that PowerShell Core is supported on [see](https://github.com/PowerShell/PowerShell#get-powershell).
@ -38,7 +38,8 @@ Save-Module -Name 'PSRule', 'PSRule.Rules.Kubernetes' -Path '.\modules';
> For pre-release versions the `-AllowPrerelease` switch must be added when calling `Install-Module` or `Save-Module`.
>
> To install pre-release module versions, upgrading to the latest version of _PowerShellGet_ may be required. To do this use:
> To install pre-release module versions, upgrading to the latest version of _PowerShellGet_ may be required.
To do this use:
>
> `Install-Module -Name PowerShellGet -Repository PSGallery -Scope CurrentUser -Force`