sigs.k8s.io/kubebuilder/v3@v3.14.0/pkg/plugins/golang/v4/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("make docker-build docker-push IMG=<some-registry>/{{ .ProjectName }}:tag"),
    49  		codeFence("make install"),
    50  		codeFence("make deploy IMG=<some-registry>/{{ .ProjectName }}:tag"),
    51  		codeFence("kubectl apply -k config/samples/"),
    52  		codeFence("kubectl delete -k config/samples/"),
    53  		codeFence("make uninstall"),
    54  		codeFence("make undeploy"),
    55  		codeFence("make build-installer IMG=<some-registry>/{{ .ProjectName }}:tag"),
    56  		codeFence("kubectl apply -f https://raw.githubusercontent.com/<org>/{{ .ProjectName }}/"+
    57  			"<tag or branch>/dist/install.yaml"),
    58  	)
    59  
    60  	return nil
    61  }
    62  
    63  //nolint:lll
    64  const readmeFileTemplate = `# {{ .ProjectName }}
    65  // TODO(user): Add simple overview of use/purpose
    66  
    67  ## Description
    68  // TODO(user): An in-depth paragraph about your project and overview of use
    69  
    70  ## Getting Started
    71  
    72  ### Prerequisites
    73  - go version v1.21.0+
    74  - docker version 17.03+.
    75  - kubectl version v1.11.3+.
    76  - Access to a Kubernetes v1.11.3+ cluster.
    77  
    78  ### To Deploy on the cluster
    79  **Build and push your image to the location specified by ` + "`IMG`" + `:**
    80  
    81  %s
    82  
    83  **NOTE:** This image ought to be published in the personal registry you specified. 
    84  And it is required to have access to pull the image from the working environment. 
    85  Make sure you have the proper permission to the registry if the above commands don’t work.
    86  
    87  **Install the CRDs into the cluster:**
    88  
    89  %s
    90  
    91  **Deploy the Manager to the cluster with the image specified by ` + "`IMG`" + `:**
    92  
    93  %s
    94  
    95  > **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin 
    96  privileges or be logged in as admin.
    97  
    98  **Create instances of your solution**
    99  You can apply the samples (examples) from the config/sample:
   100  
   101  %s
   102  
   103  >**NOTE**: Ensure that the samples has default values to test it out.
   104  
   105  ### To Uninstall
   106  **Delete the instances (CRs) from the cluster:**
   107  
   108  %s
   109  
   110  **Delete the APIs(CRDs) from the cluster:**
   111  
   112  %s
   113  
   114  **UnDeploy the controller from the cluster:**
   115  
   116  %s
   117  
   118  ## Project Distribution
   119  
   120  Following are the steps to build the installer and distribute this project to users.
   121  
   122  1. Build the installer for the image built and published in the registry:
   123  
   124  %s
   125  
   126  NOTE: The makefile target mentioned above generates an 'install.yaml'
   127  file in the dist directory. This file contains all the resources built
   128  with Kustomize, which are necessary to install this project without
   129  its dependencies.
   130  
   131  2. Using the installer
   132  
   133  Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
   134  
   135  %s
   136  
   137  ## Contributing
   138  // TODO(user): Add detailed information on how you would like others to contribute to this project
   139  
   140  **NOTE:** Run ` + "`make help`" + ` for more information on all potential ` + "`make`" + ` targets
   141  
   142  More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
   143  
   144  ## License
   145  {{ .License }}
   146  `
   147  
   148  func codeFence(code string) string {
   149  	return "```sh" + "\n" + code + "\n" + "```"
   150  }