mirror of
https://github.com/FairwindsOps/polaris.git
synced 2026-05-08 18:26:43 +00:00
1a8fb44b78
* first pass * fix up homepage * more work * housekeeping * add script to modify home link * add check docs * build docs site * Create CNAME * fix path to check-docs * update from template * fix logo in readme * fix link * remove logspam * remove old folders * fix all links * fix up readme * change up Insights description * add customization docs * phrasing * title * titles * titles * change webhook docs * refresh template * rebuild site * refresh from template repo * phrasing * add tagline * update readme\, add readme sync script * fix logo * rebuild * fix readme script * rebuild
50 lines
18 KiB
HTML
50 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>Contributing | Fairwinds Polaris Documentation</title>
|
|
<meta name="generator" content="VuePress 1.7.1">
|
|
<link rel="icon" href="/favicon.png">
|
|
<script src="/scripts/modify.js"></script>
|
|
<script src="/scripts/leadlander.js"></script>
|
|
<meta name="description" content="Documentation for Fairwinds Polaris - audit and enforce Kubernetes best practices for your workloads">
|
|
|
|
<link rel="preload" href="/assets/css/0.styles.db69974e.css" as="style"><link rel="preload" href="/assets/js/app.65b94829.js" as="script"><link rel="preload" href="/assets/js/3.0cb25b42.js" as="script"><link rel="preload" href="/assets/js/2.28adca5d.js" as="script"><link rel="preload" href="/assets/js/16.cb0515ce.js" as="script"><link rel="prefetch" href="/assets/js/10.9d1a1701.js"><link rel="prefetch" href="/assets/js/11.d7eadcf0.js"><link rel="prefetch" href="/assets/js/12.85c0eab0.js"><link rel="prefetch" href="/assets/js/13.0487faf0.js"><link rel="prefetch" href="/assets/js/14.60ea393e.js"><link rel="prefetch" href="/assets/js/15.00f25aaa.js"><link rel="prefetch" href="/assets/js/17.013e9969.js"><link rel="prefetch" href="/assets/js/18.a0fcb2d2.js"><link rel="prefetch" href="/assets/js/19.9fe045af.js"><link rel="prefetch" href="/assets/js/20.5bcacf34.js"><link rel="prefetch" href="/assets/js/21.2f58615f.js"><link rel="prefetch" href="/assets/js/22.90ebc6b9.js"><link rel="prefetch" href="/assets/js/4.be9896b6.js"><link rel="prefetch" href="/assets/js/5.665b3e6a.js"><link rel="prefetch" href="/assets/js/6.a5e340ed.js"><link rel="prefetch" href="/assets/js/7.dbd47d64.js"><link rel="prefetch" href="/assets/js/8.5a82b7c2.js"><link rel="prefetch" href="/assets/js/9.4f55b6b3.js">
|
|
<link rel="stylesheet" href="/assets/css/0.styles.db69974e.css">
|
|
</head>
|
|
<body>
|
|
<div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/" class="home-link router-link-active"><img src="/img/fairwinds-logo.svg" alt="Fairwinds Polaris Documentation" class="logo"> <span class="site-name can-hide">Fairwinds Polaris Documentation</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="https://github.com/FairwindsOps/polaris" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
View on GitHub
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="https://github.com/FairwindsOps/polaris" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
View on GitHub
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav> <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><a href="/" class="sidebar-heading clickable router-link-active open"><span>Polaris</span> <!----></a> <ul class="sidebar-links sidebar-group-items"><li><a href="/changelog/" class="sidebar-link">Changelog</a></li><li><a href="/code-of-conduct/" class="sidebar-link">Code of Conduct</a></li><li><a href="/contributing/" aria-current="page" class="active sidebar-link">Contributing</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Ways to Run Polaris</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/dashboard/" class="sidebar-link">Dashboard</a></li><li><a href="/admission-controller/" class="sidebar-link">Admission Controller</a></li><li><a href="/infrastructure-as-code/" class="sidebar-link">Infrastructure as Code</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Customization</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/customization/configuration/" class="sidebar-link">Configuration</a></li><li><a href="/customization/checks/" class="sidebar-link">Check Settings</a></li><li><a href="/customization/custom-checks/" class="sidebar-link">Custom Checks</a></li><li><a href="/customization/exemptions/" class="sidebar-link">Exemptions</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Checks</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/checks/security/" class="sidebar-link">Security</a></li><li><a href="/checks/efficiency/" class="sidebar-link">Efficiency</a></li><li><a href="/checks/reliability/" class="sidebar-link">Reliability</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="contributing"><a href="#contributing" class="header-anchor">#</a> Contributing</h1> <p>Issues, whether bugs, tasks, or feature requests are essential for keeping Polaris great. We believe it should be as easy as possible to contribute changes that get things working in your environment. There are a few guidelines that we need contributors to follow so that we can keep on top of things.</p> <h2 id="code-of-conduct"><a href="#code-of-conduct" class="header-anchor">#</a> Code of Conduct</h2> <p>This project adheres to a <a href="/code-of-conduct.html">code of conduct</a>. Please review this document before contributing to this project.</p> <h2 id="sign-the-cla"><a href="#sign-the-cla" class="header-anchor">#</a> Sign the CLA</h2> <p>Before you can contribute, you will need to sign the <a href="https://cla-assistant.io/fairwindsops/polaris" target="_blank" rel="noopener noreferrer">Contributor License Agreement<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</p> <h2 id="project-structure"><a href="#project-structure" class="header-anchor">#</a> Project Structure</h2> <p>Polaris is built on top of <a href="https://github.com/kubernetes-sigs/controller-runtime" target="_blank" rel="noopener noreferrer">controller-runtime<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>. It can run in 3 different modes, a dashboard, a webhook, or a reporter that prints or exports validation results. All of these modes make use of the shared <code>validator</code> and <code>config</code> packages. Adding new validations is possible by only making additions to those packages.</p> <h2 id="getting-started"><a href="#getting-started" class="header-anchor">#</a> Getting Started</h2> <p>We label issues with the <a href="https://github.com/FairwindsOps/polaris/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22" target="_blank" rel="noopener noreferrer">"good first issue" tag<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> if we believe they'll be a good starting point for new contributors. If you're interested in working on an issue, please start a conversation on that issue, and we can help answer any questions as they come up.</p> <h2 id="setting-up-your-development-environment"><a href="#setting-up-your-development-environment" class="header-anchor">#</a> Setting Up Your Development Environment</h2> <h3 id="prerequisites"><a href="#prerequisites" class="header-anchor">#</a> Prerequisites</h3> <ul><li>A properly configured Golang environment with Go 1.11 or higher</li> <li>If you want to see the local changes you make on a Polaris dashboard, you will need access to a Kubernetes cluster defined in <code>~/.kube/config</code></li></ul> <h3 id="installation"><a href="#installation" class="header-anchor">#</a> Installation</h3> <ul><li>Install the project with <code>go get github.com/fairwindsops/polaris</code></li> <li>Change into the polaris directory which is installed at <code>$GOPATH/src/github.com/fairwindsops/polaris</code></li> <li>See the dashboard with <code>go run main.go dashboard</code>, then open http://localhost:8080/</li> <li>See the audit data <code>go run main.go audit</code>. This command shows the audit information on the command line.</li></ul> <h2 id="running-tests"><a href="#running-tests" class="header-anchor">#</a> Running Tests</h2> <p>The following commands are all required to pass as part of Polaris testing:</p> <div class="language- extra-class"><pre class="language-text"><code>go list ./... | grep -v vendor | xargs golint -set_exit_status
|
|
go list ./... | grep -v vendor | xargs go vet
|
|
go test ./pkg/... -v -coverprofile cover.out
|
|
</code></pre></div><h2 id="creating-a-new-issue"><a href="#creating-a-new-issue" class="header-anchor">#</a> Creating a New Issue</h2> <p>If you've encountered an issue that is not already reported, please create a <a href="https://github.com/FairwindsOps/polaris/issues" target="_blank" rel="noopener noreferrer">new issue<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>, choose <code>Bug Report</code>, <code>Feature Request</code> or <code>Misc.</code> and follow the instructions in the template.</p> <h2 id="creating-a-pull-request"><a href="#creating-a-pull-request" class="header-anchor">#</a> Creating a Pull Request</h2> <p>Each new pull request should:</p> <ul><li>Reference any related issues</li> <li>Add tests that show the issues have been solved</li> <li>Pass existing tests and linting</li> <li>Contain a clear indication of if they're ready for review or a work in progress</li> <li>Be up to date and/or rebased on the master branch</li></ul> <h2 id="creating-a-new-release"><a href="#creating-a-new-release" class="header-anchor">#</a> Creating a new release</h2> <h3 id="patch-releases"><a href="#patch-releases" class="header-anchor">#</a> Patch releases</h3> <p>Patch releases only need to change this repo. The Helm chart and deploy scripts
|
|
will automatically pull in the latest changes.</p> <p>If the release involves changes to anything in the <code>deploy/</code> folder (e.g. new RBAC permissions),
|
|
it needs to be a minor or major release in order to prevent breaking the Helm chart.</p> <ol><li>Create a PR for this repo
|
|
<ol><li>Bump the version number in:
|
|
<ol><li>main.go</li> <li>README.md</li></ol></li> <li>Update CHANGELOG.md</li> <li>Merge your PR</li></ol></li> <li>Tag the latest branch for this repo
|
|
<ol><li>Pull the latest commit for the <code>master</code> branch (which you just merged in your PR)</li> <li>Run <code>git tag $VERSION && git push --tags</code></li> <li>Make sure CircleCI runs successfully for the new tag - this will push images to quay.io and create a release in GitHub
|
|
<ol><li>If CircleCI fails, check with Codeowners ASAP</li></ol></li></ol></li></ol> <h3 id="minor-major-releases"><a href="#minor-major-releases" class="header-anchor">#</a> Minor/Major releases</h3> <p>Minor and major releases need to change both this repository and the
|
|
<a href="https://github.com/FairwindsOps/charts/" target="_blank" rel="noopener noreferrer">Helm chart repo<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</p> <p>The steps are:</p> <ol><li>Modify the <a href="https://github.com/FairwindsOps/charts/stable/polaris" target="_blank" rel="noopener noreferrer">Helm chart<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> <ol><li>Clone the helm charts repo
|
|
<ol><li><code>git clone https://github.com/FairwindsOps/charts</code></li> <li><code>git checkout -b yourname/update-polaris</code></li></ol></li> <li>Bump the version number in:
|
|
<ol><li>stable/polaris/README.md</li> <li>stable/polaris/Chart.yaml</li> <li>stable/polaris/values.yaml</li></ol></li> <li>Make any necessary changes to the chart to support the new version of Polaris (e.g. new RBAC permissions)</li> <li><strong>Don't merge yet!</strong></li></ol></li> <li>Create a PR for this repo
|
|
<ol><li>Create a new branch named <code>yourname/update-version</code></li> <li>Bump the version number in:
|
|
<ol><li>main.go</li> <li>README.md</li></ol></li> <li>Regenerate the deployment files. Assuming you've cloned the charts repo to <code>~/git/charts</code>:
|
|
<ol><li><code>CHARTS_DIR=~/git/charts ./scripts/generate-deployment-files.sh</code></li></ol></li> <li>Update CHANGELOG.md</li> <li>Merge your PR</li></ol></li> <li>Tag the latest branch for this repo
|
|
<ol><li>Pull the latest for the <code>master</code> branch</li> <li>Run <code>git tag $VERSION && git push --tags</code></li> <li>Make sure CircleCI runs successfully for the new tag - this will push images to quay.io and create a release in GitHub
|
|
<ol><li>If CircleCI fails, check with Codeowners ASAP</li></ol></li></ol></li> <li>Create and merge a PR for your changes to the Helm chart</li></ol></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/FairwindsOps/polaris/edit/master/docs-md/contributing.md" target="_blank" rel="noopener noreferrer">Help us improve this page</a> <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev">
|
|
←
|
|
<a href="/code-of-conduct/" class="prev">
|
|
Code of Conduct
|
|
</a></span> <span class="next"><a href="/dashboard/">
|
|
Dashboard
|
|
</a>
|
|
→
|
|
</span></p></div> <div class="custom-footer"><div class="left-footer"><a href="https://fairwinds.com" target="_blank">Learn more about Fairwinds</a> <a href="https://fairwinds.com/insights" target="_blank">Try Fairwinds Insights</a></div> <div class="right-footer"><a href="https://www.fairwinds.com/privacy-policy" target="_blank">Privacy Policy</a></div></div></main></div><div class="global-ui"></div></div>
|
|
<script src="/assets/js/app.65b94829.js" defer></script><script src="/assets/js/3.0cb25b42.js" defer></script><script src="/assets/js/2.28adca5d.js" defer></script><script src="/assets/js/16.cb0515ce.js" defer></script>
|
|
</body>
|
|
</html>
|