-
Notifications
You must be signed in to change notification settings - Fork 138
/
client.go
1371 lines (1186 loc) · 43 KB
/
client.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
package functions
import (
"bufio"
"bytes"
"context"
"crypto/sha256"
"errors"
"fmt"
"io"
"io/fs"
"net/http"
"os"
"path/filepath"
"runtime"
"strings"
"time"
"gopkg.in/yaml.v2"
"knative.dev/func/pkg/scaffolding"
"knative.dev/func/pkg/utils"
)
const (
// DefaultRegistry through which containers of functions will be shuttled.
DefaultRegistry = "index.docker.io"
// DefaultTemplate is the default function signature / environmental context
// of the resultant function. All runtimes are expected to have at least
// one implementation of each supported function signature. Currently that
// includes an HTTP Handler ("http") and Cloud Events handler ("events")
DefaultTemplate = "http"
// DefaultStartTimeout is the suggested startup timeout to use by
// runner implementations.
DefaultStartTimeout = 60 * time.Second
)
var (
// DefaultPlatforms is a suggestion to builder implementations which
// platforms should be the default. Due to spotty implementation support
// use of this set is left up to the discretion of the builders
// themselves. In the event the builder receives build options which
// specify a set of platforms to use in leau of the default (see the
// BuildWithPlatforms functionl option), the builder should return
// an error if the request can not proceed.
DefaultPlatforms = []Platform{
{OS: "linux", Architecture: "amd64"},
{OS: "linux", Architecture: "arm64"},
{OS: "linux", Architecture: "arm", Variant: "v7"}, // eg. RPiv4
}
)
// Platform upon which a function may run
type Platform struct {
OS string
Architecture string
Variant string
}
// Client for managing function instances.
type Client struct {
repositoriesPath string // path to repositories
repositoriesURI string // repo URI (overrides repositories path)
verbose bool // print verbose logs
builder Builder // Builds a runnable image source
pusher Pusher // Pushes function image to a remote
deployer Deployer // Deploys or Updates a function
runner Runner // Runs the function locally
remover Remover // Removes remote services
lister Lister // Lists remote services
describer Describer // Describes function instances
dnsProvider DNSProvider // Provider of DNS services
registry string // default registry for OCI image tags
repositories *Repositories // Repositories management
templates *Templates // Templates management
instances *InstanceRefs // Function Instances management
transport http.RoundTripper // Customizable internal transport
pipelinesProvider PipelinesProvider // CI/CD pipelines management
startTimeout time.Duration // default start timeout for all runs
}
// Builder of function source to runnable image.
type Builder interface {
// Build a function project with source located at path.
Build(context.Context, Function, []Platform) error
}
// Pusher of function image to a registry.
type Pusher interface {
// Push the image of the function.
// Returns Image Digest - SHA256 hash of the produced image
Push(ctx context.Context, f Function) (string, error)
}
// PushUsernameKey is a type available for use to communicate a basic
// authentication username to pushers which support this method.
type PushUsernameKey struct{}
// PushPasswordKey is a type available for use as a context key for
// providing a basic auth password to pushers which support this method.
type PushPasswordKey struct{}
// PushTokenKey is a type available for use as a context key for providing a
// token (for example a jwt bearer token) to pushers which support this method.
type PushTokenKey struct{}
// Deployer of function source to running status.
type Deployer interface {
// Deploy a function of given name, using given backing image.
Deploy(context.Context, Function) (DeploymentResult, error)
}
type DeploymentResult struct {
Status Status
URL string
Namespace string
}
// Status of the function from the DeploymentResult
type Status int
const (
Failed Status = iota
Deployed
Updated
)
// Runner runs the function locally.
type Runner interface {
// Run the function, returning a Job with metadata, error channels, and
// a stop function. The process can be stopped by running the returned stop
// function, either on context cancellation or in a defer.
// The duration is the time to wait for the job to start.
Run(context.Context, Function, time.Duration) (*Job, error)
}
// Remover of deployed services.
type Remover interface {
// Remove the function from remote.
Remove(ctx context.Context, name string, namespace string) error
}
// Lister of deployed functions.
type Lister interface {
// List the functions currently deployed.
List(ctx context.Context, namespace string) ([]ListItem, error)
}
type ListItem struct {
Name string `json:"name" yaml:"name"`
Namespace string `json:"namespace" yaml:"namespace"`
Runtime string `json:"runtime" yaml:"runtime"`
URL string `json:"url" yaml:"url"`
Ready string `json:"ready" yaml:"ready"`
}
// Describer of function instances
type Describer interface {
// Describe the named function in the remote environment.
Describe(ctx context.Context, name, namespace string) (Instance, error)
}
// Instance data about the runtime state of a function in a given environment.
//
// A function instance is a logical running function space, which share
// a unique route (or set of routes). Due to autoscaling and load balancing,
// there is a one to many relationship between a given route and processes.
// By default the system creates the 'local' and 'remote' named instances
// when a function is run (locally) and deployed, respectively.
// See the .InstanceRefs(f) accessor for the map of named environments to these
// function information structures.
type Instance struct {
// Route is the primary route of a function instance.
Route string
// Routes is the primary route plus any other route at which the function
// can be contacted.
Routes []string `json:"routes" yaml:"routes"`
Name string `json:"name" yaml:"name"`
Image string `json:"image" yaml:"image"`
Namespace string `json:"namespace" yaml:"namespace"`
Subscriptions []Subscription `json:"subscriptions" yaml:"subscriptions"`
}
// Subscriptions currently active to event sources
type Subscription struct {
Source string `json:"source" yaml:"source"`
Type string `json:"type" yaml:"type"`
Broker string `json:"broker" yaml:"broker"`
}
// DNSProvider exposes DNS services necessary for serving the function.
type DNSProvider interface {
// Provide the given name by routing requests to address.
Provide(Function) error
}
// PipelinesProvider manages lifecyle of CI/CD pipelines used by a function
type PipelinesProvider interface {
Run(context.Context, Function) (string, Function, error)
Remove(context.Context, Function) error
ConfigurePAC(context.Context, Function, any) error
RemovePAC(context.Context, Function, any) error
}
// New client for function management.
func New(options ...Option) *Client {
// Instantiate client with static defaults.
c := &Client{
builder: &noopBuilder{output: os.Stdout},
pusher: &noopPusher{output: os.Stdout},
deployer: &noopDeployer{output: os.Stdout},
remover: &noopRemover{output: os.Stdout},
lister: &noopLister{output: os.Stdout},
describer: &noopDescriber{output: os.Stdout},
dnsProvider: &noopDNSProvider{output: os.Stdout},
pipelinesProvider: &noopPipelinesProvider{},
transport: http.DefaultTransport,
startTimeout: DefaultStartTimeout,
}
c.runner = newDefaultRunner(c, os.Stdout, os.Stderr)
for _, o := range options {
o(c)
}
// Initialize sub-managers using now-fully-initialized client.
c.repositories = newRepositories(c)
c.templates = newTemplates(c)
c.instances = newInstances(c)
return c
}
// RepositoriesPath accesses the currently effective repositories path,
// which can be set using the WithRepositoriesPath option.
func (c *Client) RepositoriesPath() (path string) {
path = c.repositories.Path()
return
}
// RepositoriesPath is a convenience method for accessing the default path to
// repositories that will be used by new instances of a Client unless options
// such as WithRepositoriesPath are used to override.
// The path will be created if it does not already exist.
func RepositoriesPath() string {
return New().RepositoriesPath()
}
// OPTIONS
// ---------
// Option defines a function which when passed to the Client constructor
// optionally mutates private members at time of instantiation.
type Option func(*Client)
// WithVerbose toggles verbose logging.
func WithVerbose(v bool) Option {
return func(c *Client) {
c.verbose = v
}
}
// WithBuilder provides the concrete implementation of a builder.
func WithBuilder(d Builder) Option {
return func(c *Client) {
c.builder = d
}
}
// WithPusher provides the concrete implementation of a pusher.
func WithPusher(d Pusher) Option {
return func(c *Client) {
c.pusher = d
}
}
// WithDeployer provides the concrete implementation of a deployer.
func WithDeployer(d Deployer) Option {
return func(c *Client) {
c.deployer = d
}
}
// WithRunner provides the concrete implementation of a deployer.
func WithRunner(r Runner) Option {
return func(c *Client) {
c.runner = r
}
}
// WithRemover provides the concrete implementation of a remover.
func WithRemover(r Remover) Option {
return func(c *Client) {
c.remover = r
}
}
// WithLister provides the concrete implementation of a lister.
func WithLister(l Lister) Option {
return func(c *Client) {
c.lister = l
}
}
// WithDescriber provides a concrete implementation of a function describer.
func WithDescriber(describer Describer) Option {
return func(c *Client) {
c.describer = describer
}
}
// WithDNSProvider proivdes a DNS provider implementation for registering the
// effective DNS name which is either explicitly set via WithName or is derived
// from the root path.
func WithDNSProvider(provider DNSProvider) Option {
return func(c *Client) {
c.dnsProvider = provider
}
}
// WithRepositoriesPath sets the location on disk to use for extensible template
// repositories. Extensible template repositories are additional templates
// that exist on disk and are not built into the binary.
func WithRepositoriesPath(path string) Option {
return func(c *Client) {
c.repositoriesPath = path
}
}
// WithRepository sets a specific URL to a Git repository from which to pull
// templates. This setting's existence precldes the use of either the inbuilt
// templates or any repositories from the extensible repositories path.
func WithRepository(uri string) Option {
return func(c *Client) {
c.repositoriesURI = uri
}
}
// WithRegistry sets the default registry which is consulted when an image
// name is not explicitly provided. Can be fully qualified, including the
// registry and namespace (ex: 'quay.io/myname') or simply the namespace
// (ex: 'myname').
func WithRegistry(registry string) Option {
return func(c *Client) {
c.registry = registry
}
}
// WithTransport sets a custom transport to use internally.
func WithTransport(t http.RoundTripper) Option {
return func(c *Client) {
c.transport = t
}
}
// WithPipelinesProvider sets implementation of provider responsible for CI/CD pipelines
func WithPipelinesProvider(pp PipelinesProvider) Option {
return func(c *Client) {
c.pipelinesProvider = pp
}
}
// WithStartTimeout sets a custom default timeout for functions which do not
// define their own. This is useful in situations where the client is
// operating in a restricted environment and all functions tend to take longer
// to start up than usual, or when the client is running functions which
// in general take longer to start. If a timeout is specified on the
// function itself, that will take precidence. Use the RunWithTimeout option
// on the Run method to specify a timeout with precidence.
func WithStartTimeout(t time.Duration) Option {
return func(c *Client) {
c.startTimeout = t
}
}
// ACCESSORS
// ---------
// Repositories accessor
func (c *Client) Repositories() *Repositories {
return c.repositories
}
// Templates accessor
func (c *Client) Templates() *Templates {
return c.templates
}
// Instances accessor
func (c *Client) Instances() *InstanceRefs {
return c.instances
}
// Repository accessor returns the default registry for use when building
// Functions which do not specify Registry or Image name explicitly.
func (c *Client) Registry() string {
return c.registry
}
// Runtimes available in totality.
// Not all repository/template combinations necessarily exist,
// and further validation is performed when a template+runtime is chosen.
// from a given repository. This is the global list of all available.
// Returned list is unique and sorted.
func (c *Client) Runtimes() ([]string, error) {
runtimes := utils.NewSortedSet()
// Gather all runtimes from all repositories into a uniqueness map
repositories, err := c.Repositories().All()
if err != nil {
return []string{}, err
}
for _, repo := range repositories {
for _, runtime := range repo.Runtimes {
runtimes.Add(runtime.Name)
}
}
// Return a unique, sorted list of runtimes
return runtimes.Items(), nil
}
// LIFECYCLE METHODS
// -----------------
// Apply (aka upsert)
//
// The general-purpose high-level method to initiate a synchronization of
// a function's source code and it's deployed instance(s).
//
// Invokes all lower-level methods, including initialization, as necessary to
// create a running function whose source code and metadata match that provided
// by the passed function instance, returning the final route and any errors.
func (c *Client) Apply(ctx context.Context, f Function) (string, Function, error) {
if f.Initialized() {
return c.Update(ctx, f)
} else {
return c.New(ctx, f)
}
}
// Update function
//
// Updates a function which has already been initialized to run the latest
// source code.
//
// Use Apply for higher level control. Use Init, Build, Push and Deploy
// independently for lower level control.
// Returns final primary route to the Function and any errors.
func (c *Client) Update(ctx context.Context, f Function) (string, Function, error) {
if !f.Initialized() {
return "", f, ErrNotInitialized{f.Root}
}
var err error
if f, err = c.Build(ctx, f); err != nil {
return "", f, err
}
if f, _, err = c.Push(ctx, f); err != nil {
return "", f, err
}
// TODO: change this later when push doesnt return built image.
// Assign this as c.Push is going to produce the built image (for now) to
// .Deploy.Image for the deployer -- figure out where to assign .Deploy.Image
// first, might be just moved above push
f.Deploy.Image = f.Build.Image
if f, err = c.Deploy(ctx, f); err != nil {
return "", f, err
}
return c.Route(ctx, f)
}
// New function.
//
// Creates a new running function from the path indicated by the config
// Function. Used by Apply when the path is not yet an initialized function.
// Errors if the path is alrady an initialized function.
//
// Use Apply for higher level control. Use Init, Build, Push, Deploy
// independently for lower level control.
//
// Returns the primary route to the function or error.
func (c *Client) New(ctx context.Context, cfg Function) (string, Function, error) {
// Always start a concurrent routine listening for context cancellation.
// On this event, immediately indicate the task is canceling.
// (this is useful, for example, when a progress listener is mutating
// stdout, and a context cancelation needs to free up stdout entirely for
// the status or error from said cancellation.
var route string
// Init the path as a new Function
f, err := c.Init(cfg)
if err != nil {
return route, cfg, err
}
// Build the now-initialized function
fmt.Fprintf(os.Stderr, "Building container image\n")
if f, err = c.Build(ctx, f); err != nil {
return route, f, err
}
// Push the produced function image
fmt.Fprintf(os.Stderr, "Pushing container image to registry\n")
if f, _, err = c.Push(ctx, f); err != nil {
return route, f, err
}
// TODO: change this later when push doesnt return built image.
// Assign this as c.Push is going to produce the built image (for now) to
// .Deploy.Image for the deployer -- figure out where to assign .Deploy.Image
// first, might be just moved above push
f.Deploy.Image = f.Build.Image
// Deploy the initialized function, returning its publicly
// addressible name for possible registration.
fmt.Fprintf(os.Stderr, "Deploying function to cluster\n")
if f, err = c.Deploy(ctx, f); err != nil {
return route, f, err
}
// Create an external route to the function
fmt.Fprintf(os.Stderr, "Creating route to function\n")
if route, f, err = c.Route(ctx, f); err != nil {
return route, f, err
}
fmt.Fprint(os.Stderr, "Done\n")
return route, f, err
}
// Initialize a new function with the given function struct defaults.
// Does not build/push/deploy. Local FS changes only. For higher-level
// control see New or Apply.
//
// <path> will default to the absolute path of the current working directory.
// <name> will default to the current working directory.
// When <name> is provided but <path> is not, a directory <name> is created
// in the current working directory and used for <path>.
func (c *Client) Init(cfg Function) (Function, error) {
// convert Root path to absolute
var err error
oldRoot := cfg.Root
cfg.Root, err = filepath.Abs(cfg.Root)
cfg.SpecVersion = LastSpecVersion()
if err != nil {
return cfg, err
}
// Create project root directory, if it doesn't already exist
if err = os.MkdirAll(cfg.Root, 0755); err != nil {
return cfg, err
}
// Create should never clobber a pre-existing function
hasFunc, err := hasInitializedFunction(cfg.Root)
if err != nil {
return cfg, err
}
if hasFunc {
return cfg, fmt.Errorf("function at '%v' already initialized", cfg.Root)
}
// Path is defaulted to the current working directory
if cfg.Root == "" {
if cfg.Root, err = os.Getwd(); err != nil {
return cfg, err
}
}
// Name is defaulted to the directory of the given path.
if cfg.Name == "" {
cfg.Name = nameFromPath(cfg.Root)
}
// The path for the new function should not have any contentious files
// (hidden files OK, unless it's one used by func)
if err := assertEmptyRoot(cfg.Root); err != nil {
return cfg, err
}
// Create a new function (in memory)
f := NewFunctionWith(cfg)
// Create a .func diretory which is also added to a .gitignore
if err = ensureRunDataDir(f.Root); err != nil {
return f, err
}
//create a .funcignore file
if err = ensureFuncIgnore(f.Root); err != nil {
return f, err
}
// Write out the new function's Template files.
if err = c.Templates().Write(&f); err != nil {
return f, err
}
// Mark the function as having been created, and that it is not to be
// considered built.
f.Created = time.Now()
err = f.Write()
if err != nil {
return f, err
}
// Load the now-initialized function.
return NewFunction(oldRoot)
}
type BuildOptions struct {
Platforms []Platform
}
type BuildOption func(c *BuildOptions)
func BuildWithPlatforms(pp []Platform) BuildOption {
return func(c *BuildOptions) {
c.Platforms = pp
}
}
// Build the function at path. Errors if the function is either unloadable or does
// not contain a populated Image.
func (c *Client) Build(ctx context.Context, f Function, options ...BuildOption) (Function, error) {
fmt.Fprintf(os.Stderr, "Building function image\n")
ctx, cancel := context.WithCancel(ctx)
defer cancel()
// If not logging verbosely, the ongoing progress of the build will not
// be streaming to stdout, and the lack of activity has been seen to cause
// users to prematurely exit due to the sluggishness of pulling large images
if !c.verbose {
c.printBuildActivity(ctx) // print friendly messages until context is canceled
}
// Options for the build task
oo := BuildOptions{}
for _, o := range options {
o(&oo)
}
// Default function registry to the client's global registry
if f.Registry == "" {
f.Registry = c.registry
}
// If no image name has been specified by user (--image), calculate.
// Image name is stored on the function for later use by deploy, etc.
var err error
if f.Image == "" {
if f.Build.Image, err = f.ImageName(); err != nil {
return f, err
}
} else {
f.Build.Image = f.Image
}
if err = c.builder.Build(ctx, f, oo.Platforms); err != nil {
return f, err
}
// write .func/built-name as running metadata which is not persisted in yaml
if err = f.WriteRuntimeBuiltImage(c.verbose); err != nil {
return f, err
}
if err = f.Stamp(); err != nil {
return f, err
}
// TODO: create a status structure and return it here for optional
// use by the cli for user echo (rather than rely on verbose mode here)
message := fmt.Sprintf("🙌 Function built: %v", f.Build.Image)
if runtime.GOOS == "windows" {
message = fmt.Sprintf("Function built: %v", f.Build.Image)
}
fmt.Fprintf(os.Stderr, "%s\n", message)
return f, err
}
// Scaffold writes a functions's scaffolding to a given path.
// It also updates the included symlink to function source 'f' to point to
// the current function's source.
func (c *Client) Scaffold(ctx context.Context, f Function, dest string) (err error) {
repo, err := NewRepository("", "") // default (embedded) repository
if err != nil {
return
}
return scaffolding.Write(dest, f.Root, f.Runtime, f.Invoke, repo.FS())
}
// printBuildActivity is a helper for ensuring the user gets feedback from
// the long task of containerized builds.
func (c *Client) printBuildActivity(ctx context.Context) {
m := []string{
"Still building",
"Still building",
"Yes, still building",
"Don't give up on me",
"Still building",
"This is taking a while",
}
i := 0
ticker := time.NewTicker(10 * time.Second)
go func() {
for {
select {
case <-ticker.C:
fmt.Fprintf(os.Stderr, "%v\n", m[i])
i++
i = i % len(m)
case <-ctx.Done():
ticker.Stop()
return
}
}
}()
}
type DeployOptions struct {
skipBuiltCheck bool
}
type DeployOption func(f *DeployOptions)
func WithDeploySkipBuildCheck(skipBuiltCheck bool) DeployOption {
return func(f *DeployOptions) {
f.skipBuiltCheck = skipBuiltCheck
}
}
// Deploy the function at path.
// Errors if the function has not been built unless explicitly instructed
// to ignore this build check.
func (c *Client) Deploy(ctx context.Context, f Function, oo ...DeployOption) (Function, error) {
options := &DeployOptions{}
for _, o := range oo {
o(options)
}
go func() {
<-ctx.Done()
}()
// Functions must be built (have an associated image) before being deployed.
// Note that externally built images may be specified in the func.yaml
if !f.Built() && !options.skipBuiltCheck {
return f, ErrNotBuilt
}
// Functions must have a name to be deployed (a path on the network at which
// it should take up residence.
if f.Name == "" {
return f, ErrNameRequired
}
// Warn if moving
changingNamespace := func(f Function) bool {
// We're changing namespace if:
return f.Deploy.Namespace != "" && // it's already deployed
f.Namespace != "" && // a specific (new) namespace is requested
(f.Namespace != f.Deploy.Namespace) // and it's different
}
// If Redeployment to NEW namespace was successful -- undeploy dangling Function in old namespace.
// On forced namespace change (using --namespace flag)
if changingNamespace(f) {
if c.verbose {
fmt.Fprintf(os.Stderr, "Moving Function from %q to %q \n", f.Deploy.Namespace, f.Namespace)
}
// c.Remove removes a Function in f.Deploy.Namespace which removes the OLD Function
// because its not updated yet (see few lines below)
err := c.Remove(ctx, "", "", f, true)
if err != nil {
// Warn when service is not found and set err to nil to continue. Function's
// service mightve been manually deleted prior to the subsequent deploy or the
// namespace is already deleted therefore there is nothing to delete
if errors.Is(err, ErrFunctionNotFound) {
fmt.Fprintf(os.Stderr, "Warning: Can't undeploy Function from namespace '%s'. The Function's service was not found. The namespace or service may have already been removed\n", f.Deploy.Namespace)
err = nil
}
return f, err
}
}
// Deploy a new or Update the previously-deployed function
if c.verbose {
fmt.Fprintf(os.Stderr, "⬆️ Deploying \n")
}
result, err := c.deployer.Deploy(ctx, f)
if err != nil {
return f, fmt.Errorf("deploy error. %w", err)
}
// Update the function to reflect the new deployed state of the Function
f.Deploy.Namespace = result.Namespace
if result.Status == Deployed {
fmt.Fprintf(os.Stderr, "✅ Function deployed in namespace %q and exposed at URL: \n %v\n", result.Namespace, result.URL)
} else if result.Status == Updated {
fmt.Fprintf(os.Stderr, "✅ Function updated in namespace %q and exposed at URL: \n %v\n", result.Namespace, result.URL)
}
return f, nil
}
// RunPipeline runs a Pipeline to build and deploy the function.
// Returned function contains applicable registry and deployed image name.
// String is the default route.
func (c *Client) RunPipeline(ctx context.Context, f Function) (string, Function, error) {
// Default function registry to the client's global registry
if f.Registry == "" {
f.Registry = c.registry
}
// Build and deploy function using Pipeline
return c.pipelinesProvider.Run(ctx, f)
}
// ConfigurePAC generates Pipeline resources on the local filesystem,
// on the cluster and also on the remote git provider (ie. GitHub, GitLab or BitBucket repo)
func (c *Client) ConfigurePAC(ctx context.Context, f Function, metadata any) error {
var err error
// Default function registry to the client's global registry
if f.Registry == "" {
f.Registry = c.registry
}
// If no image name has been yet defined (not yet built/deployed), calculate.
// Image name is stored on the function for later use by deploy, etc.
if f.Deploy.Image == "" {
if f.Deploy.Image, err = f.ImageName(); err != nil {
return err
}
}
// saves image name/registry to function's metadata (func.yaml), and
// does not explicitly update the last created build stamp
// (i.e. changes to the function during ConfigurePAC should not cause the
// next deploy to skip building)
if err = f.Write(); err != nil {
return err
}
// Build and deploy function using Pipeline
if err := c.pipelinesProvider.ConfigurePAC(ctx, f, metadata); err != nil {
return fmt.Errorf("failed to run generate pipeline: %w", err)
}
return nil
}
// RemovePAC deletes generated Pipeline as Code resources on the local filesystem and on the cluster
func (c *Client) RemovePAC(ctx context.Context, f Function, metadata any) error {
// Build and deploy function using Pipeline
if err := c.pipelinesProvider.RemovePAC(ctx, f, metadata); err != nil {
return fmt.Errorf("failed to remove git related resources: %w", err)
}
return nil
}
// Route returns the current primary route to the function at root.
//
// Note that local instances of the Function created by the .Run
// method are not considered here. This method is intended to specifically
// apply to the logical group of function instances actually available as
// network sevices; this excludes local testing instances.
//
// For access to these local test function instances routes, use the instances
// manager directly ( see .Instances().Get() ).
func (c *Client) Route(ctx context.Context, f Function) (string, Function, error) {
// Ensure that the allocated final address is enabled with the
// configured DNS provider.
// NOTE:
// DNS and TLS are provisioned by Knative Serving + cert-manager,
// but DNS subdomain CNAME to the Kourier Load Balancer is
// still manual, and the initial cluster config to suppot the TLD
// is still manual.
if err := c.dnsProvider.Provide(f); err != nil {
return "", f, err
}
if f.Deploy.Namespace == "" {
return "", Function{}, errors.New("Unable to route function without a namespace. Is it deployed?")
}
// Return the correct route.
instance, err := c.Instances().Remote(ctx, f.Name, f.Deploy.Namespace)
if err != nil {
return "", f, err
}
return instance.Route, f, nil
}
type RunOptions struct {
StartTimeout time.Duration
}
type RunOption func(c *RunOptions)
// RunWithStartTimeout sets a specific timeout for this run request to start.
// If not provided, the client's run timeout (set by default to
// DefaultRunTimeout and configurable via the WithRunTimeout client
// instantiation option) is used.
func RunWithStartTimeout(t time.Duration) RunOption {
return func(c *RunOptions) {
c.StartTimeout = t
}
}
// Run the function whose code resides at root.
// On start, the chosen port is sent to the provided started channel
func (c *Client) Run(ctx context.Context, f Function, options ...RunOption) (job *Job, err error) {
oo := RunOptions{}
for _, o := range options {
o(&oo)
}
if !f.Initialized() {
return nil, fmt.Errorf("can not run an uninitialized function")
}
// timeout for this run task.
timeout := c.startTimeout // client's global setting is the default
if f.Run.StartTimeout != 0 { // Function value, if defined, takes precidence
timeout = f.Run.StartTimeout
}
if oo.StartTimeout != 0 { // Highest precidence is an option passed to Run
timeout = oo.StartTimeout
}
// Run the function, which returns a Job for use interacting (at arms length)
// with that running task (which is likely inside a container process).
if job, err = c.runner.Run(ctx, f, timeout); err != nil {
return
}
// Return to the caller the effective port, a function to call to trigger
// stop, and a channel on which can be received runtime errors.
return job, nil
}
// Describe a function. Name/Namespace takes precedence if provided. If no
// name/namespace is provided, the function passed is described based off of
// its name and currently deployed namespace.
func (c *Client) Describe(ctx context.Context, name, namespace string, f Function) (d Instance, err error) {
// If name is provided, it takes precedence.
// Otherwise load the function defined at root.
// It is up to the concrete implementation whether or not namespace is
// also required.
if name != "" {
return c.describer.Describe(ctx, name, namespace)
}
// If the function's not initialized, then we can save some time and
// fail fast.
if !f.Initialized() {
return d, fmt.Errorf("function not initialized: %v", f.Root)
}
// If the function is undeployed, we can't describe it either.
if f.Name == "" {
return d, fmt.Errorf("unable to describe without a name. %v", ErrNameRequired)
}
return c.describer.Describe(ctx, f.Name, f.Deploy.Namespace)
}
// List currently deployed functions.
// If namespace is empty, the static implementation of the current
// "Lister" is used, which for example with the knative lister defaults to
// using the current kubernetes context namespace, falling back to the static
// default "namespace".
func (c *Client) List(ctx context.Context, namespace string) ([]ListItem, error) {
// delegate to concrete implementation of lister entirely.
return c.lister.List(ctx, namespace)
}
// Remove a function. Name takes precedence. If no name is provided, the
// function defined at root is used if it exists. If calling this directly
// namespace must be provided in .Deploy.Namespace field except when using mocks
// in which case empty namespace is accepted because its existence is checked
// in the sub functions remover.Remove and pipilines.Remove
func (c *Client) Remove(ctx context.Context, name, namespace string, f Function, all bool) error {
// Default to name/namespace, fallback to passed Function
if name == "" {
name = f.Name
namespace = f.Deploy.Namespace
}