sigs.k8s.io/kubebuilder/v3@v3.14.0/pkg/plugins/golang/v3/scaffolds/internal/templates/readme.go (about)

     1  /*
     2  Copyright 2022 The Kubernetes Authors.
     3  
     4  Licensed under the Apache License, Version 2.0 (the "License");
     5  you may not use this file except in compliance with the License.
     6  You may obtain a copy of the License at
     7  
     8      http://www.apache.org/licenses/LICENSE-2.0
     9  
    10  Unless required by applicable law or agreed to in writing, software
    11  distributed under the License is distributed on an "AS IS" BASIS,
    12  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13  See the License for the specific language governing permissions and
    14  limitations under the License.
    15  */
    16  
    17  package templates
    18  
    19  import (
    20  	"fmt"
    21  	"strings"
    22  
    23  	"sigs.k8s.io/kubebuilder/v3/pkg/machinery"
    24  )
    25  
    26  var _ machinery.Template = &Readme{}
    27  
    28  // Readme scaffolds a README.md file
    29  type Readme struct {
    30  	machinery.TemplateMixin
    31  	machinery.BoilerplateMixin
    32  	machinery.ProjectNameMixin
    33  
    34  	License string
    35  }
    36  
    37  // SetTemplateDefaults implements file.Template
    38  func (f *Readme) SetTemplateDefaults() error {
    39  	if f.Path == "" {
    40  		f.Path = "README.md"
    41  	}
    42  
    43  	f.License = strings.Replace(
    44  		strings.Replace(f.Boilerplate, "/*", "", 1),
    45  		"*/", "", 1)
    46  
    47  	f.TemplateBody = fmt.Sprintf(readmeFileTemplate,
    48  		codeFence("kubectl apply -k config/samples/"),
    49  		codeFence("make docker-build docker-push IMG=<some-registry>/{{ .ProjectName }}:tag"),
    50  		codeFence("make deploy IMG=<some-registry>/{{ .ProjectName }}:tag"),
    51  		codeFence("make uninstall"),
    52  		codeFence("make undeploy"),
    53  		codeFence("make install"),
    54  		codeFence("make run"),
    55  		codeFence("make manifests"))
    56  
    57  	return nil
    58  }
    59  
    60  //nolint:lll
    61  const readmeFileTemplate = `# {{ .ProjectName }}
    62  // TODO(user): Add simple overview of use/purpose
    63  
    64  ## Description
    65  // TODO(user): An in-depth paragraph about your project and overview of use
    66  
    67  ## Getting Started
    68  You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
    69  **Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster ` + "`kubectl cluster-info`" + ` shows).
    70  
    71  ### Running on the cluster
    72  1. Install Instances of Custom Resources:
    73  
    74  %s
    75  
    76  2. Build and push your image to the location specified by ` + "`IMG`" + `:
    77  
    78  %s
    79  
    80  3. Deploy the controller to the cluster with the image specified by ` + "`IMG`" + `:
    81  
    82  %s
    83  
    84  ### Uninstall CRDs
    85  To delete the CRDs from the cluster:
    86  
    87  %s
    88  
    89  ### Undeploy controller
    90  UnDeploy the controller from the cluster:
    91  
    92  %s
    93  
    94  ## Contributing
    95  // TODO(user): Add detailed information on how you would like others to contribute to this project
    96  
    97  ### How it works
    98  This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).
    99  
   100  It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/),
   101  which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster.
   102  
   103  ### Test It Out
   104  1. Install the CRDs into the cluster:
   105  
   106  %s
   107  
   108  2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
   109  
   110  %s
   111  
   112  **NOTE:** You can also run this in one step by running: ` + "`make install run`" + `
   113  
   114  ### Modifying the API definitions
   115  If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
   116  
   117  %s
   118  
   119  **NOTE:** Run ` + "`make --help`" + ` for more information on all potential ` + "`make`" + ` targets
   120  
   121  More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
   122  
   123  ## License
   124  {{ .License }}
   125  `
   126  
   127  func codeFence(code string) string {
   128  	return "```sh" + "\n" + code + "\n" + "```"
   129  }